Resource:Votemanager: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
m (Fixed example)
 
(19 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{Resource page}}
__NOTOC__
__NOTOC__
This script manages any kind of poll with multiple options. Votemap, votekick and voteban are built in.
This script manages any kind of poll with multiple options. '''votemap''', '''votekick''', '''votekill''' and '''voteban''' are built in.
==Functions==
==Built-in polls==
 
'''votemap''' (starts a vote between a random list of up to 9 maps compatible with the current gamemode, if one is running)
 
'''votemap gamemode''' (starts a vote between a random list of up to 9 maps compatible with the specified gamemode)
 
'''votemap gamemode map''' (starts a vote to launch the specified gamemode with the specified map)
 
'''votemap map''' (starts a vote to change to another map for the current gamemode, if one is running)
 
'''votemode''' (starts a vote between a random list of up to 9 gamemodes. once the vote is done and a new gamemode is picked, automatically starts 'votemap gamemode')
 
'''votekick player''' (starts a vote to kick the specified player)
 
'''votekill player''' (starts a vote to kill the specified player)
 
'''voteban player''' (starts a vote to ban the specified player)
 
==Serverside functions==
===startPoll===
===startPoll===
<syntaxhighlight lang="lua">bool, int startPoll ( table pollData )</syntaxhighlight>
<syntaxhighlight lang="lua">bool, int startPoll ( table pollData )</syntaxhighlight>
Line 7: Line 26:


* '''pollData''' is a table containing poll settings and an array of ''at least two'' options. Each option comes in the form:
* '''pollData''' is a table containing poll settings and an array of ''at least two'' options. Each option comes in the form:
<syntaxhighlight lang="lua">{string optionName,function functionToExecute,[ default=bool isDefault, arguments... ] }</syntaxhighlight>
<syntaxhighlight lang="lua">
The chosen option will be executed as functionToExecute(arguments...) when the poll ends. If there's not enough votes, the default option will be executed if there's one.
{
string optionName,
string eventToTrigger,
[element triggerFrom = getRootElement()],
default = [bool isDefaultOption = false],
var argument1,
var argument2,
...
}
</syntaxhighlight>
The chosen option will trigger eventToTrigger from the triggerFrom element with ''arguments...'' as parameters when the poll ends.
 
If there's not enough votes, the default option will be executed if there's one.


Example:
Example:
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
local playerToKill = getRandomPlayer()
local notEnoughVotesMessage = "Not enough votes to kill "..getPlayerName(playerToKill).."."
startPoll {
startPoll {
--start settings (dictionary part)
  --start settings (dictionary part)
title="Kill "..playername.."?", --required
  title="Kill "..getPlayerName(playerToKill).."?",
percentage=75, --optional
  percentage=75,
timeout=30, --optional
  timeout=30,
allowchange=false, --optional
  allowchange=false,
maxnominations=3, --optional
  maxnominations=3,
visibleTo=getRootElement(), --this can be either a parent element or a table of players
  visibleTo=getRootElement(),
--start options (array part)
  --start options (array part)
[1]={"Yes",killPlayer,player},
  [1]={"Yes", "doKillPlayer", playerToKill},
[2]={"No",outputChatBox,"votekill: Not enough votes to kill "..playername..".",getRootElement(),vR,vG,vB; default=true},
  [2]={"No", "doOutputChatBox", notEnoughVotesMessage, getRootElement(), vR, vG, vB; default=true},
}</syntaxhighlight>
}
*'''percentage''': percentage of votes needed to pass
</syntaxhighlight>
*'''timeout''': timeout in seconds
*'''title''' (required): the poll title which will be seen by clients on the manager GUI
*'''allowchange''': specifies if changing your vote is allowed
*'''percentage''' (optional, defaults to default.percentage): percentage needed for an option to pass
*'''maxnominations''': specifies the max number of renominations after a draw
*'''timeout''' (optional, defaults to default.timeout): poll timeout in seconds
*'''visibleTo''': a table or players that can see the poll, or an element that contains the players
*'''allowchange''' (optional, defaults to default.allowchange): specifies if changing your vote is allowed
 
*'''maxnominations''' (optional, defaults to default.maxnominations): specifies the max number of nominations in case there's a draw
You can use ''call'' to call any functions belonging to any other resource. Also, the syntax gets a bit more complicated if we want to evaluate code when the poll ends:
*'''visibleTo''' (optional, defaults to [[getRootElement]]()): a table or players that will be able to see the poll, OR an element that contains the players.
<syntaxhighlight lang="lua">{"myOption",loadstring("killPlayer(getRandomPlayer())") }</syntaxhighlight>
If it is root, new players joining the server will be able to vote.


''voteconfig.xml'' defaults will be used for missing optional settings.
''voteconfig.xml'' defaults will be used for missing optional settings.


===stopPoll===
===stopPoll===
<syntaxhighlight lang="lua">bool stopPoll ( void )</syntaxhighlight>
<syntaxhighlight lang="lua">bool, int stopPoll ( )</syntaxhighlight>
Stops the running poll. Returns ''true'' if the current poll was stopped successfully, ''false'' if there wasn't one.
Stops the running poll. Returns ''true'' if the current poll was stopped successfully, ''false'' and an error code otherwise.


===voteMap===
===voteMap===
<syntaxhighlight lang="lua">bool, int voteMap ( string mapName )</syntaxhighlight>
<syntaxhighlight lang="lua">bool, int voteMap ( string mapName )</syntaxhighlight>
Starts a votemap. Returns ''true'' if it was successfully started, ''false'' and an error code otherwise.
Starts a votemap. Returns ''true'' if it was successfully started, ''false'' and an error code otherwise.
* Note: It won't change the map yet as there's no map manager.


===voteBetweenMaps===
===voteBetweenMaps===
<syntaxhighlight lang="lua">bool, int voteBetweenMaps ( string mapName1, string mapName2, [ string mapName3, ... ] )</syntaxhighlight>
<syntaxhighlight lang="lua">bool, int voteBetweenMaps ( resource map1, resource map2, [ resource map3, ... ] )</syntaxhighlight>
Starts a poll to choose a map. Returns ''true'' if it was successfully started, ''false'' and an error code otherwise.
Starts a poll to choose a map. Returns ''true'' if it was successfully started, ''false'' and an error code otherwise.
* Note: It won't change the map yet as there's no map manager.


===voteKick===
===voteKick===
<syntaxhighlight lang="lua">bool, int voteKick ( string playerName )</syntaxhighlight>
<syntaxhighlight lang="lua">bool, int voteKick ( player thePlayer )</syntaxhighlight>
Starts a votekick. Returns ''true'' if it was successfully started, ''false'' and an error code otherwise.
Starts a votekick. Returns ''true'' if it was successfully started, ''false'' and an error code otherwise.
===voteKill===
<syntaxhighlight lang="lua">bool, int voteKill ( player thePlayer )</syntaxhighlight>
Starts a votekill. Returns ''true'' if it was successfully started, ''false'' and an error code otherwise.


===voteBan===
===voteBan===
<syntaxhighlight lang="lua">bool, int voteBan ( string playerName )</syntaxhighlight>
<syntaxhighlight lang="lua">bool, int voteBan ( player thePlayer )</syntaxhighlight>
Starts a voteban. Returns ''true'' if it was successfully started, ''false'' and an error code otherwise.
Starts a voteban. Returns ''true'' if it was successfully started, ''false'' and an error code otherwise.


==Events==
==Serverside events==
===onPollStarting===
<syntaxhighlight lang="lua">void onPollStarting ( table pollData )</syntaxhighlight>
Fired before a poll is starting. Allow other resources to modify the poll. Use onPollModified to send the poll back.
 
===onPollModified===
<syntaxhighlight lang="lua">void onPollModified ( table pollData )</syntaxhighlight>
You can use it to send the modified poll.
 
===onPollStart===
===onPollStart===
<syntaxhighlight lang="lua">void onPollStart ( void )</syntaxhighlight>
<syntaxhighlight lang="lua">void onPollStart ( )</syntaxhighlight>
Fired before a poll starts. Cancelling it will abort the poll.
Fired before a poll starts. Cancelling it aborts the poll.
 
===onPollStop===
<syntaxhighlight lang="lua">void onPollStop (  )</syntaxhighlight>
Fired before a poll is halted. Cancelling it prevents the poll from being halted.
 
===onPollEnd===
<syntaxhighlight lang="lua">void onPollEnd ( chosenOption )</syntaxhighlight>
Fired after a poll finished. Cancelling it has no effect.<br />
'''chosenOption''': Returns a number of the chosen option.


===onPollDraw===
===onPollDraw===
<syntaxhighlight lang="lua">void onPollDraw ( void )</syntaxhighlight>
<syntaxhighlight lang="lua">void onPollDraw ( )</syntaxhighlight>
Fired when a poll ends in a draw. Cancelling it will abort renominations.
Fired when a poll ends in a draw. Cancelling it aborts renominations.


===onClientSendVote===
===onClientSendVote===
<syntaxhighlight lang="lua">void onClientSendVote ( int vote )</syntaxhighlight>
<syntaxhighlight lang="lua">void onClientSendVote ( int vote )</syntaxhighlight>
Fired when a vote is sent to the server. Cancelling it will discard the vote.
Fired when a vote is sent to the server. ''client'' is the client who sent the vote. Cancelling it makes the manager ignore the client's choice.
 
==Default settings==
<syntaxhighlight lang="xml">
<settings>
<setting name="*color" value="#DF6464" />
<setting name="*log_votes" value="[true]" />
 
<setting name="*default.timeout" value="[30]"/>
<setting name="*default.allowchange" value="[false]"/>
<setting name="*default.percentage" value="[75]"/>
<setting name="*default.maxnominations" value="[3]"/>
 
<setting name="*votemap.enabled" value="[true]"/>
<setting name="*votemap.timeout" value="[30]"/>
<setting name="*votemap.locktime" value="[60]"/>
<setting name="*votemap.percentage" value="[70]"/>
<setting name="*votemap.allowchange" value="[true]"/>
<setting name="*votekick.enabled" value="[true]"/>
<setting name="*votekick.timeout" value="[30]"/>
<setting name="*votekick.locktime" value="[120]"/>
<setting name="*votekick.percentage" value="[75]"/>
<setting name="*votekick.allowchange" value="[true]"/>
<setting name="*voteban.enabled" value="[false]"/>
<setting name="*voteban.timeout" value="[30]"/>
<setting name="*voteban.locktime" value="[120]"/>
<setting name="*voteban.percentage" value="[85]"/>
<setting name="*voteban.allowchange" value="[true]"/>
<setting name="*votekill.enabled" value="[true]"/>
<setting name="*votekill.timeout" value="[30]"/>
<setting name="*votekill.locktime" value="[120]"/>
<setting name="*votekill.percentage" value="[75]"/>
<setting name="*votekill.allowchange" value="[true]"/>


==Configs==
</settings>
'''voteconfig.xml''': default settings for a poll
</syntaxhighlight>


'''managerconfig.xml''': votemap/kick/ban state, command block interval and individual percent.
[[ru:Resource:Votemanager]]

Latest revision as of 23:18, 3 July 2012

This script manages any kind of poll with multiple options. votemap, votekick, votekill and voteban are built in.

Built-in polls

votemap (starts a vote between a random list of up to 9 maps compatible with the current gamemode, if one is running)

votemap gamemode (starts a vote between a random list of up to 9 maps compatible with the specified gamemode)

votemap gamemode map (starts a vote to launch the specified gamemode with the specified map)

votemap map (starts a vote to change to another map for the current gamemode, if one is running)

votemode (starts a vote between a random list of up to 9 gamemodes. once the vote is done and a new gamemode is picked, automatically starts 'votemap gamemode')

votekick player (starts a vote to kick the specified player)

votekill player (starts a vote to kill the specified player)

voteban player (starts a vote to ban the specified player)

Serverside functions

startPoll

bool, int startPoll ( table pollData )

Creates a poll. Returns true if the poll was created successfully, false and an error code otherwise (see the source for error codes).

  • pollData is a table containing poll settings and an array of at least two options. Each option comes in the form:
{
string optionName,
string eventToTrigger,
[element triggerFrom = getRootElement()],
default = [bool isDefaultOption = false],
var argument1,
var argument2,
...
}

The chosen option will trigger eventToTrigger from the triggerFrom element with arguments... as parameters when the poll ends.

If there's not enough votes, the default option will be executed if there's one.

Example:

local playerToKill = getRandomPlayer()
local notEnoughVotesMessage = "Not enough votes to kill "..getPlayerName(playerToKill).."."
startPoll {
   --start settings (dictionary part)
   title="Kill "..getPlayerName(playerToKill).."?",
   percentage=75,
   timeout=30,
   allowchange=false,
   maxnominations=3,
   visibleTo=getRootElement(),
   --start options (array part)
   [1]={"Yes", "doKillPlayer", playerToKill},
   [2]={"No", "doOutputChatBox", notEnoughVotesMessage, getRootElement(), vR, vG, vB; default=true},
}
  • title (required): the poll title which will be seen by clients on the manager GUI
  • percentage (optional, defaults to default.percentage): percentage needed for an option to pass
  • timeout (optional, defaults to default.timeout): poll timeout in seconds
  • allowchange (optional, defaults to default.allowchange): specifies if changing your vote is allowed
  • maxnominations (optional, defaults to default.maxnominations): specifies the max number of nominations in case there's a draw
  • visibleTo (optional, defaults to getRootElement()): a table or players that will be able to see the poll, OR an element that contains the players.

If it is root, new players joining the server will be able to vote.

voteconfig.xml defaults will be used for missing optional settings.

stopPoll

bool, int stopPoll ( )

Stops the running poll. Returns true if the current poll was stopped successfully, false and an error code otherwise.

voteMap

bool, int voteMap ( string mapName )

Starts a votemap. Returns true if it was successfully started, false and an error code otherwise.

voteBetweenMaps

bool, int voteBetweenMaps ( resource map1, resource map2, [ resource map3, ... ] )

Starts a poll to choose a map. Returns true if it was successfully started, false and an error code otherwise.

voteKick

bool, int voteKick ( player thePlayer )

Starts a votekick. Returns true if it was successfully started, false and an error code otherwise.

voteKill

bool, int voteKill ( player thePlayer )

Starts a votekill. Returns true if it was successfully started, false and an error code otherwise.

voteBan

bool, int voteBan ( player thePlayer )

Starts a voteban. Returns true if it was successfully started, false and an error code otherwise.

Serverside events

onPollStarting

void onPollStarting ( table pollData )

Fired before a poll is starting. Allow other resources to modify the poll. Use onPollModified to send the poll back.

onPollModified

void onPollModified ( table pollData )

You can use it to send the modified poll.

onPollStart

void onPollStart (  )

Fired before a poll starts. Cancelling it aborts the poll.

onPollStop

void onPollStop (  )

Fired before a poll is halted. Cancelling it prevents the poll from being halted.

onPollEnd

void onPollEnd ( chosenOption )

Fired after a poll finished. Cancelling it has no effect.
chosenOption: Returns a number of the chosen option.

onPollDraw

void onPollDraw (  )

Fired when a poll ends in a draw. Cancelling it aborts renominations.

onClientSendVote

void onClientSendVote ( int vote )

Fired when a vote is sent to the server. client is the client who sent the vote. Cancelling it makes the manager ignore the client's choice.

Default settings

<settings>
	<setting name="*color" value="#DF6464" />
	<setting name="*log_votes" value="[true]" />

	<setting name="*default.timeout" value="[30]"/>
	<setting name="*default.allowchange" value="[false]"/>
	<setting name="*default.percentage" value="[75]"/>
	<setting name="*default.maxnominations" value="[3]"/>

	<setting name="*votemap.enabled" value="[true]"/>
	<setting name="*votemap.timeout" value="[30]"/>
	<setting name="*votemap.locktime" value="[60]"/>
	<setting name="*votemap.percentage" value="[70]"/>
	<setting name="*votemap.allowchange" value="[true]"/>
	
	<setting name="*votekick.enabled" value="[true]"/>
	<setting name="*votekick.timeout" value="[30]"/>
	<setting name="*votekick.locktime" value="[120]"/>
	<setting name="*votekick.percentage" value="[75]"/>
	<setting name="*votekick.allowchange" value="[true]"/>
	
	<setting name="*voteban.enabled" value="[false]"/>
	<setting name="*voteban.timeout" value="[30]"/>
	<setting name="*voteban.locktime" value="[120]"/>
	<setting name="*voteban.percentage" value="[85]"/>
	<setting name="*voteban.allowchange" value="[true]"/>
	
	<setting name="*votekill.enabled" value="[true]"/>
	<setting name="*votekill.timeout" value="[30]"/>
	<setting name="*votekill.locktime" value="[120]"/>
	<setting name="*votekill.percentage" value="[75]"/>
	<setting name="*votekill.allowchange" value="[true]"/>

</settings>