This guide will show you all you can do with VoteRoulette, simple to advanced. By providing examples and tips, this will be your one stop shop for setting up VoteRoulette. Use the table of contents on the right to help you quickly navigate to where you want to go.

Video Tutorials

Portuguese: http://youtu.be/JFncLIMZPOc (by AbsintoJ)

Main Configuration

Notification Settings

Settings specific to notifications and messages that VoteRoulette sends out.

General Settings

Various settings that customize how you want VoteRoulette to work.

GUI Settings

Settings that edit VoteRoulette's GUI features.

Reward Options

Settings pertaining to the awards called "Rewards", view the Configuring Awards section below to learn how to create them.

Milestone Options

Settings pertaining to the awards called "Milestones", view the Configuring Award section below to learn how to create them.

Blacklists

Settings that pertain to blacklists available for VoteRoulette.

Configuring Awards

Currently, there are 2 types of awards that you can have VoteRoulette give to players:

1. Reward - The base award that can be given to a player every time they vote.
2. Milestone - Given to a player when they reach a certain amount of votes.

All awards are created and saved in the awards.yml file. VoteRoulette comes with an in-game Award Creator that allows you to easily create Rewards/Milestones without having to mess with the file. If you are comfortable with working in YAML, however, visiting the Manual Creation section will show you how to set up awards manually.

Using the Award Creator

The Award Creator allows you to easily create awards in-game. No config editing needed! The Award Creator doesn't require you to use a bunch of long or cumbersome commands, instead you type your input straight into chat (Don't worry, others wont see your text)! It quickly walks you through each step, while still letting you customize every aspect of an award if you want.

To create an award, simply type:

/vr create

and follow the prompts.

Award Creator Tips

• Since the AC relies heavy on the chat feed, it's a good idea to turn off player chat while creating awards if you have a talkative player base. To do this, open the Minecraft's Options page, click on "Multiplayer Settings...", then click the "Chat:" button till it says "Commands Only".
• Some things you can always type, no what matter what step you are on:
  • cancel - Leaves the AC, and cancels the creation of an award.
  • pause - Leaves the AC, but pauses the creation of an award.
  • current - Makes the AC restate the directions for the step you are on, if you got lost.
  • back - Takes you back to your last step.
  • preview - See a GUI preview of the award you are working on.
  • clear - If you are on a step where you can add/edit an award prize or option, this will clear the current setting.
  • help - Shows a help menu containing a lot of the information found here.

Manual Award Creation

The following will detail each type of award and how to manually create and customize them in the awards.yml. It's recommended that you look at the Tips section before you start editing the file.

Rewards

Regular Rewards are the backbone of VoteRoulette and what you will be likely working with the most. Unlike most other listeners, VoteRoulette lets you set up multiple Rewards and you can fine tune exactly what each Reward is. While the core concept of VoteRoulette is having multiple Rewards and randomly giving one to the player when they vote, you still have lots of control over the when, who, and where of Rewards. The following will have examples of different things you can do with a Reward.

Basic Reward Customization

At their base level, Rewards require two things: A unique name and something to give. Rewards are differentiated by their names (players can also see the names, so have fun with them!) and must not be empty to be considered valid. Let's take a look at an example:

    A Basic Reward:
        xpLevels: 5

"A Basic Reward" is this Reward's unique name and it gives 5 XP levels. VoteRoulette knows the 5 XP levels belongs to "A Basic Reward" because the xp setting is indented 4 spaces from the Reward name, indicating the xp to be a child of the parent (Reward).➞ Read about YAML basics
There are 4 prize types a Reward can give: items, currency (If you have Vault installed), XP levels, and commands to be run by the console. Each Reward can contain any combination of these. Let's go over how to add each.

XP Levels

To have a Reward give XP, include a "xpLevels" node under the Reward name with how many levels to give.

    A Basic Reward:
        xpLevels: 5

Currency

To have a Reward give money, include a "currency" node with how much to give. Currency will only be given if you have the Vault plugin installed.

    A Basic Reward:
        currency: 25

Currency also supports cents, such as 5.50, 0.01, or 12.25.

Items

To have a Reward give in-game items/blocks, include an "items" node with the IDs of each item. For each item in a Reward, you can specify the amount to give with an "amount" node. Here's a Reward that gives 5 diamonds and 32 dirt blocks.

    A Basic Reward:
        items:
            264:
                amount: 5
            3:
                amount: 32

Items can be heavily customized in VR, the more advanced uses are detailed in the Advanced Item Customization section below.

Commands

To have a Reward issue commands, include a "commands" node with a list of commands. The commands must be in a list format. It does not matter if you include a "/" in the beginning or not. You can also have a players name inserted into the command using the %player% variable. The following example shows a Reward that runs two commands. When this Reward is won, the server will say "Voting is cool!" and the voting player will get creative mode.

    A Basic Reward:
        commands:
            - /say Voting is cool!
            - /gamemode creative %player%

Commands have some advanced functions that are detailed in the Advanced Commands Customization section below.

Combining Prize Types

A single Reward can have multiple different prizes together. To do this, it's as easy as putting all the prizes under one Reward. If you wanted a Reward that gives 1 diamond, 10 xp levels, and $50, you could set it up like this:

    A Basic Reward:
        currency: 50
        items:
            264:
                amount: 1
        xpLevels: 10

Keep in mind, the order in which you list the prizes of a Reward does not matter.

Multiple Rewards

To make multiple rewards, all you need to do is start a new line with a unique Reward name. Here's an example of what multiple rewards could look like:

    20 Dollars In My Pocket:
        currency: 20

    Time To Enchant:
        xpLevels: 30

    Ooh Shiny:
        items:
            264:
                amount: 1

Advanced Reward Customization

Rewards have many options to further customize them to fit your needs. This section will go over all the advanced customization you can do with each Reward.

Permission Groups

If you want make Rewards that are only available to certain permission groups, you can do so by specifying what groups qualify. To set permission groups, use a "permGroups" section under a Reward, with each group separated by a comma. Keep in mind that to use this feature, you must have Vault installed.

    Advanced Reward:
        currency: 500
        permGroups: Donators, Subscribers

In this example, only players in the Donators and Subscribers group will get this reward.

Players

Sometimes you may find yourself wanting to set a Reward to be for only a handful of people, not an entire permission group. You can do this with the a "players" section under a Reward. Separating each player with a coma.

    Advanced Reward:
        currency: 100000
        players: Notch, Dinnerbone, Herobrine

You can use the players node in conjunction with the permGroups node to fine tune all the players you want getting this Reward. For example, say you had a Reward set for a VIP perm group and there was a couple other players not in the VIP group that you want to also be eligible.

Worlds

If you use plugins like Multiverse-Inventories, you probably want to be able to set Rewards for specific worlds. Do so by including a "worlds" node under a Reward. Separating each world with a comma.

    Advanced Reward:
        xpLevels: 30
        worlds: pvp_main, pvp_arena

There are other world settings that are covered in the Main Configuration section above.

Websites

It's possible to specify what server lists a Reward is eligible for. To do this, include a "websites" node under a Reward and specify websites by their identifiers, separated by commas. Each server list website sends over an identifier when a player votes and sometimes this identifier is just the URL of the website but this isn't always the case. So to make it easier to figure out the identifiers for each website, a file is generated in VoteRoulette's data folder called "known websites". Every time a vote comes through, VoteRoulette saves the identifier of the website to this file, if it hasn't already.

    Advanced Reward:
        xpLevels: 30
        websites: PlanetMinecraft.com, Minestatus, MCSL

Advanced Items

VoteRoulette has extensive options to create ultra customized in-game items for Rewards.
Each Reward can contain multiple items and each item has options for setting an amount, a custom name, a lore description, enchantments, a data ID, and even the color of leather armor. Custom names and lore descriptions support color codes and they can also dynamically insert the voting player's name for further personalization.
The following will go over different examples of item setups to give you an idea of what you can do.

Example 1:
A Reward that gives a diamond sword with a custom name, lore description, and powerful enchants.

    God Sword:
        items:
            276:
                amount: 1
                name: "%red%The Discipliner"
                lore: "%player%'s reward for voting!"
                enchants: sharpness(5), fire aspect(3), looting(3)

Breaking down the item:
- The "name" node gives the item it's custom name.
- The "lore" node sets the lore description of the item. If you want to have separate lines of lore, you can either separate them by comas or list each line. Example:

                lore: "This is the first line, This is the second line, This is the third line"
                
                lore: 
                    - "This is the first line"
                    - "This is the second line"
                    - "This is the third line"

- The "enchants" node sets the enchants on an item, with each enchant separated by a comma. You can also specify the level of the enchantment in parenthesis at the end of an enchant name. You can put whatever enchant level you like, including unnatural levels, for example: efficiency(6)

Example 2:
A Reward that gives 5 villager spawn eggs

    Lets Trade:
        items:
            383:
                dataID: 120
                amount: 5

Breaking down the item:
- The "dataID" node allows you to specify the custom ID of an item
- dataID's are most often used for items such as: spawn eggs, potions, and colored blocks (wool, clay, glass).

Example 3:
A Reward that gives a set of multicolored leather armor.

    Tie-Dye Set:
        items:
            298:
                armorColor: yellow
                amount: 1
            299:
                armorColor: blue
                amount: 1
            300:
                armorColor: 39,49,250
                amount: 1
            301:
                armorColor: green
                amount: 1

Breaking down the item:
- The "armorColor" node allows you to specify color of the leather armor
- You can specify colors in two ways: a color name or an RGB value.

Example 4:
A Reward that gives 2 fire resistance potions and 2 potions of healing.

    Medicine Man:
        items:
            373:
                multiple:
                    fire resistance:
                        dataID: 8195
                        amount: 2
                    healing:
                        dataID: 8197
                        amount: 2

Breaking down the item:
- The "multiple" node allows you to specify multiple items that have the same item ID but different data ID's
- The reason you can't just have a second item with the same ID below the first is because YAML files cannot read multiple values that are identical on the same path. This is the same reason why each Reward must have a unique name.
- Once you have the "multiple" node, use a unique identifier to specify each different item and put the item options after each one. The identifier can be anything you wish, just make sure they are different from one another. In the example above, the type of potion was used to make it easier to read.

Advanced Commands

Commands that are ran by Rewards can be delayed. Delayed commands can also be set to automatically run early if a player logs off or if the server shuts down before the delay has happened. To set a delay, prefix the command with the amount of seconds you want the delay to be in parenthesis. If you want the delayed command to be automatically run if the player logs off or if the server shuts down, include "logoff" and/or "shutdown" in the parenthesis as well. Separate them from the delay amount and each other with forward slashes. The order in which you write the delay settings does not matter.

    Advanced Reward:
        commands:
            - (5) /say Voting is cool!
            - (60/logoff) /gamemode creative %player%

In the example above, the "/say" command is delayed 5 seconds. The "/gamemode" command is delayed 60 seconds but will automatically run if the player logs off of before then. If the command did not run when they logged off, then the command would possibly run while the player is offline and it wouldn't work. The player would not have creative mode the next time they logged in.

Here are some examples of how you can use delayed commands:

Example 1:
A Reward that gives fly mode for 5 minutes.

    Flying Like An Eagle:
        commands:
            - /fly %player%
            - (300/logoff) /fly %player%

Example 2:
A Reward that teases the player.

    Jokes, I say:
        commands:
            - /tell %player% Sorry this reward has nothing...
            - (5/logoff) /tell %player% Just kidding, here's a diamond.
            - (5/logoff) /give %player% diamond 1

Example 3:
A Reward that emulates a timed permission. Give "disguisecraft.mob.creeper" for 3 hours.
(This uses GroupManager commands, as an example)

    Do The Creep:
        commands:
            - /manuaddp %player% disguisecraft.mob.creeper
            - (10800/shutdown)/manudelp %player% disguisecraft.mob.creeper

Chance

If you want to change how often a Reward is given to a player, you can do so with chance settings. Chance in VoteRoulette is set up to be as flexible as possible. You can specify and setup chance a number of ways and these ways effect how Rewards are given differently. To set a chance for a Reward, include a "chance" node with a percentage.

    All of the Diamonds:
        items:
            264:
                amount: 64
        chance: 1%

You can also specify chance by writing it as "#/#". For example, "1/200" would be a 1 in 200 chance.

Some things to understand about chance in VoteRoulette:

• Decimal percentages are not supported. Instead write the chance as "#/#" . For example, "1/200" equals 0.5%.
• To simply account for the most possible setups, VoteRoulette checks the chance per Reward, instead of all together. So for example, if you have 2 Rewards at 50% chance each, VoteRoulette does a chance check for the first Reward (at 50%), if that fails, VoteRoulette goes to the next Reward and checks the chance for that. Because of this, a player could possibly get no Rewards chosen even though the two Rewards each have 50% which could be seen as adding up to 100% of possibilities covered.
• If you have multiple Rewards with chances and some without chances specified, VoteRoulette will do the chance checks for the ones with chance, and if none were chosen, VoteRoulette will pick a random one from the list of Rewards without chances set.
• If all of your Rewards have chances specified, and none of them pass their chance check, a player won't receive anything.

Reroll

Setting a reroll for a Reward allows the possibility of giving some extra stuff to the player on top of the original Reward! The reroll function is flexible and you can tailor it to you needs. You can include a custom chance for the reroll thats different from the Rewards default chance (if it has one).If you don't include a chance, the Rewards own chance will be used, and if it doesn't have one, then the player will always receive it! You can also specify a list of rewards to be considered and you can have the list considered by using one of two modifiers: RANDOM or ALL.
RANDOM: Random simply selects a random reward from the given list of rewards. If the selected reward has any chance settings, it will check those and then administer the reward to the player if the chance check passes. If the chance check fails, the reroll process stops.
ALL: The all modifier goes through each reward in the given list, checking chances until once passes or it runs out of rewards to check. This is mimics the process that happens when a player votes.

Reroll examples:

Example 1:
    Diamondz:
        items:
            264:
                amount: 5
        reroll: Moar Diamondz (50%)
    Moar Diamondz:
        items:
            264:
                amount: 2
        chance: 0%

Example 2:
    Awesomesauce:
        items:
            264:
                amount: 5
        reroll: ALL [Dirt For You(40%), Epic Sword(1%), Extra Diamond(20%)]

In the first example, if a player receives the reward "Diamondz", they have a 50% chance to also get the Reward "Moar Diamondz".

• Notice that "Moar Diamondz" has default chance of 0%, meaning they would never get this otherwise!
• You can specify chance for reroll Rewards the same as you would normally (IE: 50%, or 1/500)

Reroll settings for a rerolled Reward (say that 5 times fast!) are not ignored, so you can chain rerolls. But be careful, you can infinite loop rerolls this way!

Vote Streak

If you want to award a player who has voted so many days consecutively in a row, you can add vote streak settings to a Reward. To do so, include a "voteStreak" node with how many days you want the streak to be.

    And On The 7th Day:
        items:
            264:
                amount: 10
        voteStreak: 7

In the example, the player would qualify for this Reward after voting 7 days in a row.

You can also include "or more" following the number of days to make the vote streak include every day after. So with "voteStreak: 7 or more", a player would qualify after voting 7 days (and every day after) in a row. Reversely, if you include "or less" following the number of days, the vote streak will include every day leading up to the set days. So "voteStreak: 3 or less", a player would qualify for the Reward after 1, 2, and 3 days of consecutive votes.

Override Default Reward Message

Whenever a player receives a Reward, they get a default message telling them they did and which one they got. That message can be edited in the messages.yml file. However, if you want to set a custom message for a specific Reward, you can do so with a "message" node. Color codes are also supported here. Example:

    Just In Case:
        items:
            264:
                amount: 64
        players: Herobrine
        message: "%aqua%I knew you would return, my lord. I give you my offerings."

Adding A Description

If you want to describe what is in a Reward, rather than relying on VoteRoulettes default way of showing the contents. You can use a "description" node.
Example:

    Falling With Style:
        commands:
            - fly %player%
            - (300) fly %player%
        description: "Fly mode for 5 minutes"

If a Reward has a custom description set, it will be shown when players type /vr reward and will also replace the %prizes% variable for the default reward message in the messages.yml.

The description node was mainly put in place for the Rewards that only ran commands, in which case appeared empty when players viewed them via /vr rewards or when they got the reward message.

Milestones

Milestones are a special type of Reward that are given to a player after they have reached a certain amount of votes. They are setup the same way as a regular Reward but have a couple extra options that you can customize and fine tune. Milestones are a great way to give your players goals and better rewards for continued voting.

Basic Milestone Customization

Just like Rewards, Milestones require a unique name and a prize to give to the player. Additionally, they require that you specify how many votes are required to reach the Milestone. You can do so with a "votes" section. Example:

    I Could Get Used To This:
        xpLevels: 10
        votes: 5

Advanced Milestone Customization

There are a few options specific to Milestones that allow you to further customize how you wish them to work.

Recurring

You may find your self wanting Milestones that happen at set intervals. You can easily do so with a "recurring" section. Setting a Milestone to be recurring means that the Milestone will happen upon multiples of the votes. For example, if votes is set to 50 and recurring is true, players will receive the Milestone every 50 votes (50, 100, 150, etc).

    Another 25 Votes, Another 25 Bucks:
        currency: 25
        votes: 25
        recurring: true

Priority

Random vs Highest Priority

Messages and Localizations Files

Tips

YAML Basics

• NEVER use the "Tab" key.
• Read mbaxter's guide to editing YAML files. It is written in context to one of his plugins, CraftIRC, but the same concepts apply.

Validating Configs

Before uploading your files to your server, it is always a good idea to run them (especially your awards.yml) through an online YAML validator whenever you make big changes. Some good ones are:

• http://instantyaml.appspot.com
• http://yamllint.com

Text Editors

Using a WYSIWYG text editor, such as Microsoft Word, is not recommended. Instead use a processor that lets you edit the files in "plain text". Some good ones are:

• TextEdit, TextWrangler (Mac OS X)
• Tea (Linux)
• Notepad, Notepad++ (Windows)

Make sure to disable any text editor features to do with "cleaning up whitespace characters", as this may insert "Tab" characters without your knowledge.