AlliedModders - VoteManager API (votekick/ban/map/burn/gravity/etc)

AlliedModders (https://forums.alliedmods.net/index.php)

- Unapproved Plugins (https://forums.alliedmods.net/forumdisplay.php?f=109)

- - VoteManager API (votekick/ban/map/burn/gravity/etc) (https://forums.alliedmods.net/showthread.php?t=57636)

VoteManager API (votekick/ban/map/burn/gravity/etc)

VoteManager

By: ferret!

Description

VoteManager provides a series of natives and forwards that other plugins can use to create votes and respond to the results. VoteManager handles creating the vote menus, and forwards the winning answer out to the client plugins.

Includes vote plugins that do the votes from my Basic Votes and Extended Votes plugins:

vmgr_kick (votekick)
vmgr_ban (voteban)
vmgr_map (votemap)
vmgr_burn (voteburn)
vmgr_bury (votebury)
vmgr_gravity (votegravity)
vmgr_alltalk (votealltalk)
vmgr_friendlyfire (voteff)

Installation

Place the plugins/vmgr_core.smx file inside of the addons/sourcemod/plugins/ folder.
Place the translations/plugins.vmgrcore.txt file inside of the addons/sourcemod/translations/ folder.
Copy the votes you want from the plugins/vmgr_votes/ folder to the addons/sourcemod/plugins/ folder.

Commands

vm_cancelvote
- Cancels any vote currently in process.
vm_vote<name>
- Runs the vote matching name.

Cvars

vm_master_limit
- Acts as a master "percentage of votes required". When this is not set to 0, it will override all cvar's that set the percentage of a vote.
- Default 0.0
- Range 0.0 (0%, off) to 1.0 (100%)
vm_showvotes
- When on, displays player selections as the vote is in progress.
- Default is on. Set to 0 to disable.
vm_sayvotes
- When on, anyone can say a vote's name in chat and cause it to begin. Plugins can turn this off if they don't want their vote to be available for say.
- Default is off. Set to 1 to enable.
vm_limit_<name>
- Sets how many votes are needed for <name> vote to be successful.
- Default is 0.60 (60%)
- Range it 0.05 (5%) to 1.0 (100%)

Changelog

Version 0.8 (July 8th)
- Initial release

Bugs, Requests, Translations, or Other Issues

Please use my project area on the Allied Modders Bug Tracker to report any issues or make requests. Your login for the bug tracker is the same as your forum login. Set the category to this plugin's name.

Please read the next post for detail usage information

Re: VoteManager API

VoteManager Basics

You should read includes/vmgr.inc as well as this post. I will detail each natives and forward here though, and provide examples.

The first thing you should do if you are going to use VMgr is detail a global variable, or if multiple votes, an array. Something like g_MyVote would work. You'll use this to store the index or "handle" for your vote. 0 is a valid index, so you should set it to -1 to start.

Code:

new g_MyVote = -1;

Code:

new g_MyVotes[5] = {-1, ...}

forward VM_OnCoreReady()

VM_OnCoreReady() will be issued when VMGR_CORE.SMX has completed loading and can actually accept vote registrations. You should have this in your plugin and use it to register the votes. Don't worry about the parameters of VM_RegisterVote, we'll get there soon.

Code:

public VM_OnCoreReady()

{

 if (g_MyVote == -1)

  g_MyVote = VM_RegisterVote("kick", "Kick", _, _, TargetType:Client, true);

}

forward VM_OnVoteStart(vote)

VM_OnVoteStart(vote) will be issued whenever a vote begins. You can compare vote to your vote indexes to find out if it's your vote. This is provided in case you wish to take some other action when your vote is ran. An example might be to PrintToChatAll some message.

Code:

public VM_OnVoteStart(vote)

{

 if (vote == g_MyVote)

  PrintToChatAll("HIS FATE IS IN YOUR HANDS? KICK HIM? YES OR NO! YOU DECIDE!");

}

forward VM_OnVoteEnd(vote, bool:result, String:item[], client, userid, String:name[], String:authid[])

This is probably the most important forward. This is called when a vote ends. Lots of parameters, right? They're documented in vmgr.inc but I'll go over them here too. The first parameter, vote, is the index that just ended. The second is true if successful, false if not. (Note: A vote for multiple actions is always successful). Item[] is the name of the item that won. Client, userid, name, and authid are all target related. If your vote doesn't have a target, they will be 0. Otherwise, they will have the target's data. VMgr provides all of this in case the target disconnected. We wouldn't want something to run away from a voteban, would we?

Code:

public VM_OnVoteEnd(vote, bool:result, String:item[], client, userid, String:name[], String:authid[])

{

 if (vote != g_MyVote)

  return;

 

 if (result)

 {

  PrintToChatAll("%t", "Kicked player", name);

  LogMessage("Votekick success, kicking \"%L\"", client);

  ServerCommand("kickid %d \"Votekicked.\"", userid);

 }

}

native bool:VM_IsCoreReady()

This native is a bit of a problem right now. Please be sure to read my next post concerning "To-Do's". The purpose of this native is to allow a plugin to check if VMgr_Core is ready. You would use this in OnPluginStart, and register your votes with it. Why? If your plugin reloads, it won't know about it's votes anymore. But since VMgr_Core didn't reload, VM_OnCoreReady won't ever occur. So this provides you a second method of finding out if the Core is there and ready. Use with care. Until "Non-required Natives" are a part of Sourcemod, doing this makes VMgr a required plugin for your's to load.

Code:

public OnPluginStart()

{

 if (VM_IsCoreReady() && g_MyVote == -1)

  g_MyVote = VM_RegisterVote("kick", "Kick", _, _, TargetType:Client, true);

}

Continued next post.

Re: VoteManager API

native bool:VM_UnregisterVote(index)

If you register a vote, you should unregister it. Use this in OnPluginUnload(). Unfortunately, this once again causes VMgr to become a required plugin, until "Non-required Natives" are a reality. This will return false if the index is invalid.

Code:

public OnPluginUnload()

{

 if (g_MyVote != -1)

  VM_UnregisterVote(g_MyVote);

}

VM_RegisterVote

Now we're down to the most important part of all this. Registering your vote.

Code:

stock VM_RegisterVote(const String:name[],

   const String:title[],

   admflag = VM_ADMINFLAG,

   VoteType:vType = VoteType:YesNo,

   TargetType:tType = TargetType:None,

   bool:say = true)

The above stock handles creating the vote. It uses several other natives to accomplish this. I won't detail them because you should use the stock, and never those natives directly. If you're interested in exactly how it works, read the include file.

VM_RegisterVote does several things. It gives your vote's information to the Core, and registers a command and a convar. The first parameter, name, should be a no-spaces single word for the vote, such as "kick". Title should be the title of the vote, such as "Kick Player". admflag is the admin flag you want the command to be restricted to. It defaults to ADMFLAG_VOTE.

vType and tType control how the vote works. I will detail both below. The last parameter, 'say', controls whether or not this vote will work from chat. It defaults to true. If you change this to false, your vote will be console command only, regardless of the value of vm_sayvotes.

Code:

g_MyVote = VM_RegisterVote("kick", "Kick", _, _, TargetType:Client, true);

g_MyVote = VM_RegisterVote("gravity", "Change Gravity", _, VoteType:MultiInt, _, true);

g_MyVote = VM_RegisterVote("ff", "Change FriendlyFire");

g_MyVote = VM_RegisterVote("burn", "Burn", _, VoteType:YesNo, TargetType:Client, true);

g_MyVote = VM_RegisterVote("map", "Change Map", _, VoteType:MultiMap, _, true);

vType and tType

Here's the enums:

Code:

enum VoteType

{

 YesNo = 0,

 MultiInt,

 MultiFloat,

 MultiString,

 MultiMap

}

 

enum TargetType

{

 None = 0,  // No target

 Client,    // Any client, including Bots

 Player     // Only players, no fake clients

}

TargetType is pretty straight forward. No target, any client, or only actual players, no fake clients.

VoteType currently has 5 options. I will probably be adding a sixth soon.

The first is the default, YesNo. In this case your vote will take a single argument, and the options displayed to the player will be Yes and No. For a vote of this type, item[] will be "Yes" or "No" when VM_OnVoteEnd is called.

The next are all MultiVotes. It should be noted that a MultiVote is ALWAYS successful. There is no failure. Each MultiVote has a type associated with it, such as Int, Float, String and Map. VMgr_Core checks the arguments supplied with the vote command against this. For example, all arguments sent with a MultiMap vote are ran through IsMapValid(). Int and Float votes are tested as well. MultiString's receive no validation. When only a single argument is provided to a MultiVote, the vote will display like a YesNo vote. The difference is that when VM_OnVoteEnd is called, item[] will be set to that argument's value, rather than Yes or No.

That's just about everything. So as an example, here is the complete vmgr_kick plugin:

Code:

#pragma semicolon 1

 

#include <sourcemod>

#include <vmgr>

 

#define PLUGIN_VERSION "1.0"

 

public Plugin:myinfo =

{

name = "VM VoteKick",

author = "ferret",

description = "VM Votekick",

version = PLUGIN_VERSION,

url = "http://www.sourcemod.net/"

};

 

new g_MyVote = -1;

 

public OnPluginStart()

{

LoadTranslations("common.phrases");

 

if (VM_IsCoreReady() && g_MyVote == -1)

g_MyVote = VM_RegisterVote("kick", "Kick", _, _, TargetType:Client, true);

}

 

public OnPluginUnload()

{

if (g_MyVote != -1)

VM_UnregisterVote(g_MyVote);

}

 

public VM_OnCoreReady()

{

if (g_MyVote == -1)

g_MyVote = VM_RegisterVote("kick", "Kick", _, _, TargetType:Client, true);

}

 

public VM_OnVoteStart(vote)

{

//Nothing

}

 

public VM_OnVoteEnd(vote, bool:result, String:item[], client, userid, String:name[], String:authid[])

{

if (vote != g_MyVote)

return;

 

if (result)

{

PrintToChatAll("%t", "Kicked player", name);

LogMessage("Votekick success, kicking \"%L\"", client);

ServerCommand("kickid %d \"Votekicked.\"", userid);

}

}

Re: VoteManager API

Known Issues

If you wish VM_UnregisterVote and VM_IsCoreReady(), your plugin will become dependant on VMgr_Core being loaded. This will be resolved when Non-Required Natives are fixed. See SM Feature Request #292. Since you DO want to Unregister your votes, this is a biggie :( Unfortunately, using VMgr at all makes it a requirement right now.
vmgr_ban does not call the OnClientBanned forward like Basic Votes' voteban and sm_ban do. SM Bug #581

To-Do

Add a sixth VoteType that treats the first argument of a vote as it's title. This is necessary to implement a generic vm_vote.
Add a forward for when the core unloads, so plugins can make sure they know their vote is no longer valid. This is important but not high priority because the core shouldn't unload. Just keep it in mind if you're playing around with it. This is also waiting on an SM Feature Request.
Add a forward for when a vote fails due to no votes received. Someone might care.
Add a native for triggering a vote directly without registering it. This will require the sixth VoteType as well. For example, RTV or MapChooser could use VMgr and the Trigger native, instead of maintaining and building votes themselves.
Add a native for a plugin to set a minimum and maximum range for MultiInt and MultiFloat
Waiting on a new version of ShowActivity that doesn't automatically prefix messages with [SM]. Until them, Vote initiated messages will have "[SM][VM]" instead of just [VM].

Re: VoteManager API

P.S. requires SM build 1084 or higher.

Re: VoteManager API

Re: VoteManager API (votekick/ban/map/burn/gravity/etc)

I plan to change VM_OnVoteStart to include target information like VM_OnVoteEnd.

Re: VoteManager API (votekick/ban/map/burn/gravity/etc)

Please reupload without subversion.

Re: VoteManager API (votekick/ban/map/burn/gravity/etc)

Reuploaded. Also moved the votes to vmgr_votes folder as original post stated.

Re: VoteManager API (votekick/ban/map/burn/gravity/etc)

Version 1.0 is almost ready.

Notable changes:

All vm_ and [VM] prefixes changed back to sm_ and [SM]
New native "TriggerVote" allows a plugin to issue a vote. Please note that TriggerVote() does NOT check your arguments. If you supply a list of maps that don't exist, VMgr Core doesn't care.
"Optional/Non-Required Native" code added
sm_vote <question> <answers> added
RegisterVote stock now allows you to specify whether or not an sm_vote<name> command should be created. Useful for people who want to use Vote Manager with their plugin with TriggerVote, but not have an actual command.
All public natives, stocks, and forwards are no longer prefixed with VM_. Sorry, I didn't like that
VM_OnCoreReady changed to OnVoteReady. I'm not 100% sure I like this change yet, may use something else. OnVMgrCoreReady?
IsCoreReady() will handle checking if vmgr_core is loaded, as part of the non-required natives code. Also will be renamed to something like "IsVoteReady()", see above note.
VoteType:MultiString uses the first NON-TARGET argument as the title of the vote. This is mostly for use with TriggerVote, but sm_vote is also a MultiString vote. I'm not 100% sure about this. I may leave MultiString like it was in 0.8, and add another VoteType for this

Stuff I'm still considering and haven't started:

Removing the static arrays used to store votes and replacing wtih new Array ADT
INS say2 support. Will probably wait to see what changes in INS 1.2