Randomized rewards for voting
This page is a work in progress!!
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.
Portuguese: http://youtu.be/JFncLIMZPOc (by AbsintoJ)
Settings specific to notifications and messages that VoteRoulette sends out.
|messagePlayer||true/false||Turn on or off the message telling the player which award they received.|
|broadcastToServer||true/false||Turn on or off broadcasting to the server when players vote.|
|onlyBroadcastOnlinePlayerVotes||true/false||If the above is true, setting this to true will make VR only broadcast online player votes.|
|broadcastCooldown||a number||The cooldown period (in minutes) before a player's votes can be broadcasted to the server again.|
|logToConsole||true/false||Turn on or off logging to console when a player votes.|
|usePeriodicReminder||true/false||Enable or disable the periodic vote reminder.|
|periodicReminderInterval||a number||How often the periodic reminder is broadcasted (in minutes), if enabled.|
|useTwentyFourHourReminder||true/false||Enable or disable the 24 hour reminder. This reminder is sent to players after 24 hours have past since their last vote.|
Various settings that customize how you want VoteRoulette to work.
|onlyConsiderPlayersPrimaryGroup||true/false||If you use inheritance with your permission groups, this setting enables or disables considering a player to be in a group they inherit.|
|autoClaimAwards||true/false||Set this to true to have players unclaimed awards auto claimed when they login.|
|disableUnclaimedAwards||true/false||Disable the saving of unclaimed awards entirely.|
|disableInventoryProtection||true/false||Disable VoteRoulette's inventory protection. This means instead of saving the award as unclaimed if the players inventory is full, the items will drop at their feet.|
|defaultCommandAlias||vr, vtr, voteroulette||Set which command alias you would like to be shown to players when they are using commands.|
|checkForUpdates||true/false||Let VoteRoulette automatically check for updates. Checks happen every 6 hours. If an update is found, admins are notified upon login.|
|debug||true/false||Turn on the debug mode. This is useful if you are not getting expected results from a particular award set up or if you are just curious about what VR is up to.|
Settings that edit VoteRoulette's GUI features.
|guiForAwards||true/false||Turn on or off the visual representation of awards.|
|showCommands||true/false||If the above is true, whether or not to show any commands that will be ran.|
|showPlayersAndGroups||true/false||If "guiForAwards" is true, whether or not to show the qualifying players and perm groups.|
|useFancyLinks||true/false||Turn on or off fancy link detection in the text for the /vote command. (Editable in the messages.yml file)|
|useScoreboard||true/false||Enable or disable the scoreboard when viewing stats.|
Settings pertaining to the awards called "Rewards", view the Configuring Awards section below to learn how to create them.
|giveRandomReward||true/false||Enable or disable VoteRoulette's reward randomization process when players vote. If you set this to false, the default reward will always be given.|
|defaultReward||a rewards name||If the above is false, this is the reward to give to players when they vote.|
|giveRewardsOnThreshold||true/false||Turn on or off the vote threshold. If on, players will only be considered for a Reward if they vote so many times.|
|voteThreshold||a number||If the above is true, this is how many votes till a player receives a reward.|
|considerRewardsForPlayersCurrentWorld||true/false||If you set any required worlds for Rewards, the following setting will make VoteRoulette consider the Rewards that qualify for the world the player is currently standing in first, and other worlds last.|
|prioritizeVoteStreaks||true/false||Turn on or off prioritizing Rewards with vote streak settings. If this is true and a player qualifies for a vote streak Reward, the Reward will be given to them, skipping the randomization process. If this is off and a player qualifies for a vote streak, the vote streak is included in the list of Rewards that are chosen at random as usual. Learn how to set vote streak settings for a Reward here.|
Settings pertaining to the awards called "Milestones", view the Configuring Award section below to learn how to create them.
|onlyGiveMilestoneUponCompletion||true/false||When a player qualifies for a Milestone, turn on or off only giving the Milestone. If off, the voting player will also be considered for a Reward on top of the Milestone.|
|giveRandomMilestone||true/false||If a player qualifies for multiple Milestones at once, turn on or off VoteRoulette choosing one at random. If off, VoteRoulette will instead use the Milestones' priority settings, giving the Milestone with the highest priority to the player.|
|randomizeTiedHighestPriorityMilestones||true/false||If a player qualifies for multiple Milestones at once, the above is false, and some Milestones tie for the highest priority, this setting turns on or off VoteRoulette choosing a random Milestone from the list of tied ones. This is a good way to mix and match the functionality of random Milestones but still having the control of priorities. If this setting is off, the first Milestone from the list of tied is chosen.|
|considerMilestonesForPlayersCurrentWorld||true/false||If you set any required worlds for Milestones, the following setting will make VoteRoulette consider the Milestones that qualify for the world the player is currently standing in first, and other worlds last.|
|randomFireworkOnMilestone||true/false||Turn on or off a randomized firework that shoots off from the player when they reach a Milestone.|
Settings that pertain to blacklists available for VoteRoulette.
|blacklistedPlayers||ist of names||List of players that will never receive awards.|
|useBlacklistAsWhitelist||true/false||Switch the above list to a whitelist, only those players will receive awards.|
|blacklistedWorlds||list of worlds||List of worlds that players can never claim awards in.|
Currently, there are 2 types of awards that you can have VoteRoulette give to players:
- Reward - The base award that can be given to a player every time they vote.
- 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:
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.
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.
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
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.
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.
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.
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.
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.
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.
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.
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
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.
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)
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).
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.
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.
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:
A Reward that gives fly mode for 5 minutes.
Flying Like An Eagle: commands: - /fly %player% - (300/logoff) /fly %player%
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
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
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.
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.
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!
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.
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 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.
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
Random vs Highest Priority
Messages and Localizations Files
- 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.
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:
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
Make sure to disable any text editor features to do with "cleaning up whitespace characters", as this may insert "Tab" characters without your knowledge.