About Voting - Steell/Ultimate-Mapchooser GitHub Wiki

Ultimate Mapchooser's voting system is based off of SourceMod's built in capabilities in mapchooser.smx. However, this functionality has been augmented to have several new features:

Ability to hold runoff votes.
Ability to block first few slots in the vote (to prevent accidental/spammed votes)
Ability to control how the votes are populated.
Sounds for when votes start and complete

On top of this, there are also some features specific to UMC:

Ability to vote for groups
Ability to vote for a group and then vote for a map from the group (tiered vote)
Maps in the vote are populated according to UMC's Weighting and Exclusion system.

This document outlines all of the features of UMC votes, in order to help you understand how various customizations will affect how a vote will behave.

##Types of Votes

There are three types of votes:

Map Votes - Similar to standard mapchooser.smx votes, players vote on a map from a list of maps. The list of maps is generated by Ultimate Mapchooser using its Exclusion and Weighting system; first, the UMC-Mapcycle is filtered to contain only maps which pass the Exclusion check, and then the remaining maps are selected at random, and how likely a map is to be selected is based off of its weight, determined by the Weighting system. How many maps are added to the vote from each group is determined by a group's "maps_invote" option (see Core Documentation).
Group Votes - Instead of voting for maps, players will instead vote for a group that is defined in the UMC-Mapcycle. Once the winning group is determined, a map from the group is selected (again, using Ultimate Mapchooser's Exclusion and Weighting system). Whether or not a group will appear in the vote is determined by the Exclusion system.
Tiered Votes - This mode combines the other two by first having players vote for a group, and then once that vote is finished, vote for a map from the group. Like the other two modes, this vote is populated according to Ultimate Mapchooser's Exclusion and Weighting system.

##Nominations Before populating a vote with the specified UMC-Mapcycle, Ultimate Mapchooser will first go through it's internal list of nominated maps to see if any of those can be placed in the vote. Nominated maps are also processed through the Exclusion and Weighting system, however they are treated differently; all modules extending the Exclusion and Weighting system are notified that the map is a nomination, so that they can be processed differently. How they are processed is determined by the module, see the module's documentation for more information.

##Vote Thresholds Votes can fail for two reasons: if nobody votes, or if the winning option in a vote does not reach a defined threshold. This threshold is a minimum percentage of votes required for the winning option to have in order for the vote to succeed.

As a simple example, let's pretend that a vote has a threshold of 50%. Now, pretend that the vote ended and the winning option received 3 out of 7 votes. If you do the math, you will see that the winning option only received about 43% of the votes. Because the threshold was set to 50%, this vote is now considered a failure.

In the event of a vote failure, two actions can be taken:

Do nothing
Hold a runoff vote (see below). Most modules have a cvar to control what will happen in the event of a failed vote.

##Runoff Votes Runoff votes, if enabled, occur in the event that a vote completed without reaching the defined threshold. A runoff vote is a second attempt at the original vote, but with some of the losing options eliminated (it will always eliminate the bottom options first).

After a runoff vote completes, the winning option is again checked to see if it has enough votes to pass the threshold. If it has enough votes, then it will set the next map as if the vote completed normally. If it has failed, then it will attempt to runoff again under the following conditions:

There were more than two options in the failed vote. If there are only two options, then the runoff algorithm cannot remove any items from the vote, so the runoff system has effectively come to a halt and the vote is considered officially a failure.
If there is a set maximum amount of runoffs per vote, and that maximum amount has not been reached. Once that amount has been reached, the runoff vote is over.

In the event that a runoff fails, there are two possible actions which can be taken:

Do nothing
Just consider the vote a success Most modules have a cvar to control what will happen in the event of a failed runoff.

Besides being able to customize a set maximum number of runoffs, you can also set a maximum number of items to appear in a runoff vote (minimum 2).

##Vote Sounds Ultimate Mapchooser can play distinct sounds for when a vote starts, ends, and when a runoff vote occurs. All of the modules which come with Ultimate Mapchooser will automatically precache each sound and add it to the server's download tables.

##Blocked Slots Ultimate Mapchooser allows for the first slots in a vote to be disabled (up to 5 slots) in order to prevent accidental or spammed votes. It is also possible to control whether or not runoff votes have blocked slots or not.

##Menu Scrambling By default, the menus are populated in the same order that the UMC-Mapcycle being used defines its groups. For example, if the mapcycle defines three groups "A", "B", and "C" in that order, then the vote will contain maps from group "A" first, then "B" second, and "C" third (or if it's a group/tired vote, the group names in that order).

If you do not want that functionality, Ultimate Mapchooser can scramble the vote, so that options appear in a random order rather than the predefined order.

##Extra Options Just like the standard mapchooser.smx, Ultimate Mapchooser allows for a Don't Change option and an Extend Map option, which will do nothing or extend the map, respectively.