InstallingUMC - Silenci0/UMC GitHub Wiki

Installation

Ultimate Mapchooser's Core and Modules are installed like any other SourceMod plugin; just move the compiled .smx file into the addons/sourcemod/plugins folder. SourceMod will then load them on map change, or they can be loaded manually via the "sm plugins load name" command in the server console (where name is the file name of the compiled plugin, without the .smx extension).

UMC Installation

To install the plugins, simply download the files, unzip them, and then copy the addons and cfg folders into your game server's main directory. This will add ALL of the files into your game's "addons/sourcemod" directories. If asked to merge folders, click yes. If asked to overwrite (assuming you are using an older version), click yes.

All files, such as translations and the .smx plugin files, have been included in the proper directory structure for Sourcemod, so it should be a simple drag and drop installation. If the plugins have been added while the server is running, it is highly recommended to restart the server in order to load everything and generate all configuration files, if necessary. That said, plugins can be loaded manually via the "sm plugins load name" command in the server console (where name is the file name of the compiled plugin, without the .smx extension) or by letting the server change maps.

UMC Mapcycle File

All maps that are to be managed by UMC will need to be added to the umc_mapcycle.txt file (which is also provided). This file can be used to create multiple map groups or give some maps the ability to appear under certain conditions in the map votes/nominations list depending on the modules you choose to utilize.

The umc_mapcycle.txt file MUST exist in the main directory of your game's server installation as that is where the plugin looks for this file by default. By default, all modules look for the name umc_mapcycle.txt in the server's root directory. It is highly recommended that you only use one mapcycle file for all of the plugins. However, If you want to rename the umc_mapcycle.txt file (not recommended) or if you want to use multiple versions of the file (again, not recommended), it is possible to do, but you will need to specify in the appropriate configuration files (such as umc_votecommand.cfg) the name of the umc-mapcycle file you want that module to use. Available options that can be used for maps/groups can be found in the umc-mapcycle.txt file and each module's wiki page will also include information on the options it manages for the umc-mapcycle file as well.

Finally

You do not have to install ALL the plugins for this to work! Each one can be added or removed as necessary due to their modular nature (this is intentional). Just make sure to install the umc_core.smx and then install any subsequent plugins that you might need for map voting.

Please be sure to disable any other mapchooser/nominate/rtv plugins including the ones that come with Sourcemod if you plan on using this plugin!_ Having both installed/used can cause undesired effects for map voting.

Please note that this plugin does work with older games/mods made on Source 2007, but some functions/features may not work correctly and/or are not available. Games made with Source 2009 or later will have most, if not all, functions/features working correctly.

Configuration

All of Ultimate Mapchooser's behavioral settings are controlled by cvars, defined in configuration files located in cfg/sourcemod and each module will have their own configuration file. Each module/plugin has its own configuration file that will generate if they do not exist on the server, but for convenience purposes, the configuration files have also been included as part of the files available for download. If an update to UMC comes out that adds new cvars to the modules, it is highly recommended to update based on the latest versions of the configuration files found in the Github repository or to auto-generate the files again by deleting the configurations and restarting the server.

For detailed instruction/information on what options are available in each module's configuration file, see the documentation for each UMC module on the wiki.

Creating a UMC-Mapcycle

All modules released with Ultimate Mapchooser that can manipulate the mapcycle in some way require a UMC-Mapcycle definition. The format for this file is defined as follows:

"umc_mapcycle" 
{ 
    "GROUP1" 
    { 
        "group_option1" "x" 
        "group_option2" "x" 
        ... 
        "group_optionN" "x"

        "MAP1"
        {
            "map_option1"  "x"
            "map_option2"  "x"
            ...
            "map_optionN"  "x"
        }

        "MAP2"
        {
             ...
        }

        ...

        "MAPN"
        {
            ...
        }
    }

    "GROUP2"
    {
        ...
    }

    ...

    "GROUPN"
    {
        ...
    }
}

In summary, a UMC-Mapcycle contains a list of groups, each with a list of maps inside. There has to be at least one group, and each group has to have at least one map in it. Here is a breakdown of what each of these are:

  • Groups: A group is defined as a subset of the maps available for selection; this means that for each group you have in your UMC-Mapcycle, there will be a corresponding entry (or multiple entries) in the vote. It also means that if a map is selected randomly from a UMC-Mapcycle, and there are multiple groups, first a random group is selected, and then a random map is selected from the group.

  • Maps: A map is defined as a combination of a map name and the group it belongs to. This means that if you have the same map in multiple groups, they are treated as distinct by default. All maps must belong to a group.

Each group and map can also have several options available to it for configuration. These options are defined by whatever modules are installed. To see what options are available from a module, please see the documentation of a specific module.

UMC Mapcycle Examples

If you want to make sure maps from different "lists" appear in the vote, then you should make more than one group, with each group corresponding to a different list. If you just want to select randomly from one big list of maps, then you should stick with only one group. It is recommended that you stick to this rule of thumb with regards to multiple groups vs. one group, otherwise you may start running into trouble with your UMC-Mapcycle.

Take this (real) example: someone designed the following UMC-Mapcycle:

"umc_mapcycle" 
{ 
    "GroupA" 
    { 
        "maps_invote" "3" 
        "default_min_players" "0" 
        "default_max_players" "16"

        "de_dust" { }
        "de_dust2" { }
        "de_aztec" { }
        "de_nuke" { }
        "cs_italy" { }
        "de_dust_csgo" { }
    }

    "GroupB"
    {
        "maps_invote"    "3"
        "default_min_players"  "17"
        "default_max_players"  "24"

        "de_dust" { }
        "de_dust2" { }
        "de_aztec" { }
        "de_nuke" { }
        "cs_italy" { }
        "de_dust_csgo" { }
        "de_inferno" { }
        "de_cbble" { }
        "de_dust2_revolution" { }
        "de_piranesi" { }
        "de_chateau" { }
        "de_prodigy" { }
        "cs_office" { }
        "cs_assault" { }
        "cs_compound" { }
        "de_port" { }
    }
}

What the above UMC-Mapcycle is set up to do is use the provided Play Limits module to specify what maps are available when different amounts of players are on the server. When there are 16 or less players on the server, the only available maps are in the "GroupA" group. When there are 17 or more players, the only available maps are in the "GroupB" group. This may look perfectly fine, and assuming it will never be changed, it will also work fine.

However, let's say that the creator of this UMC-Mapcycle wanted to change the minimum required players for "cs_office" in "GroupB" to "12". This means that when there between 12 and 16 players on the server, two groups will be available for selection: "GroupA" with all of its maps, and "GroupB" with "cs_office". If a vote were to appear (with UMC's default voting settings), it would loke something like this: Vote for the next map! 1. 2. 3. 4. cs_office No matter what with this new mapcycle, when there are between 12 and 16 players on the server, "cs_office" will be added to the vote. This is because, as explained earlier, UMC's Map Groups are there to divide the group into different pools of maps. In order to resolve such an issue, the proper way to write the above mapcycle would be like this:

"umc_mapcycle" 
{ 
    "All Maps" 
    { 
        "maps_invote" "3"

        "de_dust" { }
        "de_dust2" { }
        "de_aztec" { }
        "de_nuke" { }
        "cs_italy" { }
        "de_dust_csgo" { }
        "de_inferno" 
        {
            "min_players"  "17"
        }
        "de_cbble" 
        {
            "min_players"  "17"
        }
        "de_dust2_revolution" 
        {
            "min_players"  "17"
        }
        "de_piranesi" 
        {
            "min_players"  "17"
        }
        "de_chateau" 
        {
            "min_players"  "17"
        }
        "de_prodigy" 
        {
            "min_players"  "17"
        }
        "cs_office" 
        {
            "min_players"  "17"
        }
        "cs_assault" 
        {
            "min_players"  "17"
        }

        "cs_compound" 
        {
            "min_players"  "17"
        }
        "de_port" 
        {
            "min_players"  "17"
        }
    }
}

With this mapcycle, the "min_players" for "cs_office" could then be changed to whatever is wanted, and it would not run into the same problem.

Upgrade Guide

Estimated Duration: 5-10 mins

First, all files that aren't your UMC-Mapcycle file (umc_mapcycle.txt by default) and your Vote Warnings definition file (vote_warnings.txt by default) will no longer be useable. You should at least hold on to your ultimate_mapchooser.cfg file since it will be a useful reference when configuring v3. All other files, including the translations and ultimate-mapchooser.smx should be removed from the server and can be deleted.

Once you've cleared all necessary files, you can install the most recent version of Ultimate Mapchooser. Make sure you don't accidentally overwrite umc_mapcycle.txt and vote_warnings.txt when installing.

Ultimate Mapchooser v3 is a little different when it comes to configuration. By default, all main features of the plugin are enabled. You can turn off individual modules by deleting the corresponding .smx files (or moving them to the addons/sourcemod/plugins/disabled folder). If you're not certain of what a module does, you can read its documentation.

Now that you're satisfied with what modules you have enabled, you can configure each module using the .cfg files located in cfg/sourcemod. Each modules .cfg will have the same name as the .smx. You will notice that v3 either has a lot more, or a lot less to cvars to set. If you're using every module, there will be a lot more to configure, but if you're using only a small amount of modules, then it's much less than previous version. The reason for the overall increase in cvars is because v3 allows much more customizability for various features, whereas in earlier version they would have to share the same cvar.

Once you're done configuring all of the modules, restart your server, and now you can then use Ultimate Mapchooser just like you always have!

Quick Guide

  1. Remove all files from previous version except for umc_mapcycle.txt and vote_warnings.txt.
  2. Install v3, make sure you don't accidentally overwrite any old files you want to save (the two in step 1).
  3. Disable any plugins (called modules) you will not be using.
  4. For all modules you keep enabled, configure them using the corresponding .cfg files located in cfg/sourcemod.
  5. Restart your server.
  6. Party on, dudes.