Editing Custom votes

Since OpenArena 0.8.5, it is possible to extend [[voting]] by setting up ''custom votes''. This OpenArena-specific feature is not supported by [[ModCompat|old mods]] designed for [[Q3A]].

Custom votes allow players to execute specific commands defined by server administrators, in addition to those usually offered by the game.<br/>
Players are able to see available custom votes using ''[[command console]]'' or ''[[ESC menu]]''.<br/>
About flexibility of this system, players can just choose from a list without specifying further values (would be a security issue); on the other hand, a single custom vote can execute a series of commands.

==Usage==
===Server setup (administrators)===
* Create a plain text file into your ''baseoa'' (or current mod, if supporting custom votes) folder. Default name for it is <tt>votecustom.cfg</tt><ref>In case you are using Microsoft Windows with the option to hide known file extensions, pay attention to do not erroneusly create a file named like ''votecustom.cfg.txt'' which would be misleading shown as ''votecustom.cfg'' in the OS. Of course, you may set OA variable to fit that double extension filename.</ref>.
* Here you can find ''an example'' of a such file with five options:
<pre>
{
votecommand	"lms_custom"
displayname	"Change to Last Man Standing on dm4ish?"
command		"g_gametype 10 ; g_instantgib 0; map dm4ish"
}
{
votecommand	"ffa_custom"
displayname	"Change to instantgib FFA on dm6ish?"
command		"g_gametype 0 ; g_instantgib 2 ; map dm6ish" // Rail+gauntlet
}
{
votecommand	"kick_all_bots"
displayname	"Kick all bots?"
command		"kick allbots" // Callvote kick allbots is disabled in OA (risky)
}
{
votecommand	"domination_500" // Domination needs higher Capturelimit
displayname	"Change to Domination and Capturelimit 500?" 
command		"capturelimit 500 ; g_gametype 12 ; map restart"
}
{
votecommand	"capturelimit_8"
displayname	"Change Capturelimit to 8?"
command		"capturelimit 8 ; map restart"
}

</pre>
'''Explaination:'''<br />
- { and } mark the beginning and the end of each custom vote entry.<br />
- "votecommand" is the name of the vote clients will ask for (<tt>/callvote custom <votecommand></tt>). '''It may not contain spaces!'''<br />
- "displayname" is the description displayed while the vote is going on.<br />
- "command" is the string that will be executed if the vote passes. The string can include more commands separated by ";".<br />
- What follows "//" in the same line is considered a "comment" and not parsed.
* Please notice that ''ESC menu'' and <tt>/callvote custom</tt> command '''will show only the first 12 custom slots''': you may create more custom options, but users would not know about their existence!
* Lauch OpenArena, load a map (e.g. <tt>/map wrackdm17</tt>).
* Check that <tt>g_votecustomfile</tt> CVAR value fits the name of your file (default value is ''votecustom.cfg''). You can change it if you wish (you may prepare more custom vote files and then change this CVAR value to switch to another set of votes); in case you do, you may need to restart the map to have clients see the new list in ''ESC menu''.
* To ''enable'' custom votes, modify <tt>g_votenames</tt> CVAR value to make it include <tt>/custom/</tt>. E.g. you may change it from its OA 0.8.8 default (<tt>/map_restart/nextmap/map/g_gametype/kick/clientkick/g_doWarmup/timelimit/fraglimit/shuffle/</tt>) to <tt>/map_restart/nextmap/map/g_gametype/kick/clientkick/g_doWarmup/timelimit/fraglimit/shuffle/'''custom/'''</tt>. Please notice that initial and final "/" are important.
** ''Tip:'' ability of command console to ''paste'' (e.g. Shift+Ins) text from your Operating System clipboard can be handy when modifying this long variable. Also, you may prepare custom [[configuration file]]s to be invoked by <tt>/exec <filename.ext></tt> to use as shortcuts to modify this variable.

If you later wish to ''disable'' custom votes, you should modify "g_votenames" to do not include "custom" (e.g. <tt>/reset g_votenames</tt> sets it back to its default value, which is everything except custom).<ref>Simply modifying ''g_votenames'' to point to a non-existent or empty custom vote file is NOT recommendend instead: clients may still see the old list (which options would not work) from a cache.</ref>

''Tip:'' you may use ''[[Message of the day]]'' to inform players about availability of custom votes in your server.

===Client usage (players)===
After admins defined their custom votes and enabled them, players can invoke custom votes using either [[ESC menu]] or [[Command console]].

* Using ''ESC menu'':
** Access ESC menu (usually, ESCAPE key on your keyboard).
** Select "CALL VOTE"; select "CUSTOM VOTE" --> Accept; select an entry in the "Call vote custom" list --> Accept.
*** In case ESC menu does not include "CALL VOTE" option, server is probably running an old [[mod]] which does not support custom votes. In case custom votes are not enabled on the server, "custom vote" will appear ''grey'' and you will not be able to select it. In case custom votes are enabled, but custom vote file is not correctly set, "Call vote custom" list should be empty (in come cases, you may still see a "cached" version of the list: you would get "Command could not be found" trying to start a such vote).
** Players will be allowed to vote "yes" or "no" as usual (usually, pressing F1 or F2 keys on keyboard).
** If the vote passes, the server will execute the predefined command associated.


* Using ''command console'':
** (Optional) Enter <tt>/callvote</tt> to check whether custom voting is active: if you can see "custom <special>" in the list, it is enabled.
** Enter <tt>/callvote custom</tt> to check which custom votes have been defined.
*** In case it returns "Invalid vote string", custom votes are not supported by current [[mod]]. In case it returns "Not allowed here", then custom votes are ''disabled'' on the server. In case it returns "Custom vote commands are:" without listing anything, custom votes file is not correctly set.
** Enter <tt>/callvote custom <votecommand></tt> to start voting (e.g. <tt>/callvote custom lms_custom</tt>).
*** In case you call vote for a not-existing custom vote entry (e.g. mistyped its name), you will receive "Command could not be found" error.
** Players will be allowed to vote "yes" or "no" as usual (usually, pressing F1 or F2 keys on keyboard... or entering <tt>/vote yes</tt> or <tt>/vote no</tt> in console).
** If the vote passes, the server will execute the predefined command associated.

==Some usage ideas==
* Modifiying ''capturelimit'' (as far as 0.8.8, there isn't yet a specific callvote for that), useful if the server can switch from ''[[Domination]]'' to other modes and vice-versa.
* Controlling the number of bots in the server, by either setting ''bot_minplayers'' value or using ''addbot'' and ''kick allbots'' commands (note: standard ''/callvote kick allbots'' has been disabled along with ''/callvote kick all'' to avoid abuses<ref>The [[Q3A]] exploit for which ''callvote kick all'' and ''callvote kick allbots'' have been disabled in OA:<small>
* Give yourself the name "All"
* Act like an idiot
* Someone calls "callvote kick all"
* Leave the game
* Vote passes
* Everyone gets kicked</small>
Repeat the same exploit for "allbots". Although less serious, it is still an exploit.</ref>, but you can get it back via custom vote, if you accept the risk of the exploit).
* Enabling or disabling [[special game options]] such as [[g_elimination]], [[vampire mode]], [[allrockets]], [[instantgib]], [[friendly fire]], etc.
** Considering the custom command can execute multiple commands separed by ";", a single menu entry can be used to disable more options at once (example: <tt>command "g_elimination 0 ; g_vampire 0 ; g_rockets 0 ; g_instantgib 0 ; map_restart"</tt>)
** Custom commands can be used with ''exec <filename.ext>'' to run even longer command series. Example: <tt>command "exec myconfig1.cfg"</tt>. 
* In case the 12 shown entries are not enough for you, you may save some by using a single slot for both enabling and disabling a feature, using ''toggle'' command <small>(see ''[[Command console#Key binding]]'')</small>: this way, every time that custom vote entry is invoked and approved, the server will change a CVAR value to the next one you previously set. Maybe this is not optimal for players, but may be useful if you need many custom votes. Examples:
<pre>
{
votecommand "gravity"
displayname "Enable/Disable low gravity?"
command "toggle g_gravitymodifier 0.6 1" // This has immediate effect
}
{
votecommand "Allrockets"
displayname "Enable/Disable all rockets?"
command "toggle g_rockets ; map_restart" // By default, TOGGLE cycles 0 and 1
}
{
votecommand "Instantgib"
displayname "Instantgib off/on/on+gauntlet?"
command "toggle g_instantgib 0 1 2 ; map_restart"
}
</pre>

==Notes==
<references />

==See also==
* [[Servers]]
* [[Manual/Multiplayer]]
* [[Configuration examples]]
[[Category:Manual]]
[[Category:Servers]]
[[Category:Configuration examples]]