Exclusion Introduction

Ultimate Mapchooser's Exclusion system checks to see if a map is considered "valid." Ultimate Mapchooser automatically filters out invalid maps so that selected maps are always valid.

Modules

Usually, new Exclusion rules are implemented in modules which extend the Exclusion system. There are two such modules which are packaged with Ultimate Mapchooser: Player Limits and Time Limits, which allow users to specify valid ranges of players and time, respectively. Other Exclusion rules can be implemented in modules by other developers.

Special Cases

The Exclusion system has two special cases: one for nominated maps, and one for maps that are just being used for display, but not for an immediate map change.

• Nominated Maps: Nominated maps are considered different because a lot of times server operators want to make special cases for them. Usually, modules which extend the Exclusion system have cvars to control whether or not nominations should be treated differently (the Player Limits and Time Limits modules have this).

• Display Maps: Maps which are just being selected for display can also be treated specially (again, most modules have a cvar to control this). An example of such a situation is in the Nominations module when a nomination menu is displayed: the items in the menu are not being used for an immediate map change, so they are treated as "display" maps.

Weight Introduction

The Weighting system is used when picking maps/groups randomly, in order to specify the "likelihood" of a map/group being picked.

When Is It Used?

The Weighting system is used in various places: when a vote menu is being populated with maps, maps are chosen from the group at random. How likely a map is going to be picked for inclusion in a vote is determined by its calculated weight. This value is calculated via the Weighting system.

Another case is when a module requests a random map from Ultimate Mapchooser (the Random Mapcycle module does this). How likely it is that the map will be picked is determined by its weight, again calculated via the Weighting system.

Modules

The Weighting system is extended in UMC modules; without any modules adjusting weights, all random selections are uniform (all weights are the same). There are two modules packaged with Ultimate Mapchooser that extend the Weighting system: Weight and Map Rate Map-Reweighting. The first of which allows users to define a "weight" and "group_weight" option for maps and map groups respectively in a UMC-Mapcycle. The second module will adjust a map's weight based off of it's average rating in the external Map Rate SourceMod Plugin.

Voting Introduction

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: 1. There were more than 2 options in the failed vote. If there are only 2 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. 1. 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.

Other

Information related to UMC that does not fit into its own category.

Insert a Map Group into a Map Vote

You can add what looks like a Map Group to a vote that only contains maps. This requires the type of vote to be a Map vote (as opposed to a Group or Tiered vote), and it requires the use of the display-template Map Group option.

How To

Take this UMC-Mapcycle as an example:

"umc_mapcycle" 
{
    "Some Maps" 
    { 
        "maps_invote" "3"

        "cp_dustbowl" {}
        "cp_granary" {}
        "cp_gravelpit" {}
        "cp_well" {}
        "cp_fastlane" {}
        "cp_badlands" {}
        "pl_goldrush" {}
        "pl_badwater" {}
    }

    "Random Choice"
    {
        "maps_invote"  "1"
        "display-template"  "Or perhaps something else..."

        "ctf_2fort" {}
        "ctf_well" {}
        "koth_viaduct" {}
        "plr_pipeline" {}
        "pl_hoodoo_final" {}
    }
} 

This will create a vote with 4 choices: the first three (assuming the menu isn't scrambled) will be taken from the "Some Maps" Map Group, and the third map will be taken from the "Random Choice" Map Group. However, since the display-template option is set to "Or perhaps something else...", then whatever map is selected from this group to be in the vote, it will appear in the vote as "Or perhaps something else..."

Multi-Mod Vote

By using the command option for Map Groups, combined with Tiered/Group Votes (or display-template with Map votes), you can make a vote that allows players to select which Mod they would like to play next.

How To

First, you should place something in your server.cfg that disables all mods, that way you don't have to worry about any mods being active accidentally (and you don't need to worry about it affecting UMC; all UMC commands are performed after server.cfg is executed, so they will override whatever is in server.cfg). Next, you should add whatever commands/convars are necessary to enable a mod to it's own .cfg. Finally, you define a UMC-Mapcycle like this:

"umc_mapcycle" 
{ 
    "Zombie Fortress" 
    { 
        "command" "exec zombie-fortress.cfg"

        "zf_dustbowl" {}
        //...other ZF maps
    }

    "VS Saxton Hale!"
    {
        "command"  "exec vs-saxton-hale.cfg"

        "vsh_Hakurei_Shrine" {}
        //...other VSH maps
    }

    //...other mods go in different groups
} 

When a vote appears, there will be an option for each mod (assuming you're using Group or Tiered Voting), and when the vote is completed, with command specified by the winning group will be executed at the start of the next map. In this case, that command will execute the appropriate .cfg, thus enabling the Mod.