Asherkin: Created page with " ----
Below is FaTony's WIP rewrite of the command tutorial, it's been remove from the main page as it's incomplete and more confusing for new users
--~~..."

2013-03-17T16:12:18Z

Created page with " ---- <div class="info">Below is FaTony's WIP rewrite of the command tutorial, it's been remove from the main page as it's incomplete and more confusing for new users<br>--~~..."

New page

----

<div class="info">Below is FaTony's WIP rewrite of the command tutorial, it's been remove from the main page as it's incomplete and more confusing for new users<br>--[[User:Asherkin|Asherkin]] ([[User talk:Asherkin|talk]]) 11:12, 17 March 2013 (CDT)</div>
=Creating client command=
So far we have learned how to set up our plugin and run some code. But our plugin still doesn't do anything useful. Let's add a console command to allow clients to see their kills/deaths ratio. For demonstration purposes, we are going to start with very naive implementation that a beginner could write, then we'll look at the common bugs it contains, fix them and add more advanced features. In the end we'll have a mature feature-rich implementation and experience that will prevent us from making simple mistakes in the future.

==Naive implementation==
First, we need to register our console command. <tt>OnPluginStart</tt> is a good place to do that. In order to register our console command, we need to use <tt>RegConsoleCmd</tt> function, it is declared inside '''console.inc''', here's how it's declared:
<pawn>/**
* Creates a console command, or hooks an already existing one.
*
* Console commands are case sensitive. However, if the command already exists in the game,
* the a client may enter the command in any case. SourceMod corrects for this automatically,
* and you should only hook the "real" version of the command.
*
* @param cmd Name of the command to hook or create.
* @param callback A function to use as a callback for when the command is invoked.
* @param description Optional description to use for command creation.
* @param flags Optional flags to use for command creation.
* @noreturn
* @error Command name is the same as an existing convar.
*/
native RegConsoleCmd(const String:cmd[], ConCmd:callback, const String:description[]="", flags=0);</pawn>
This native looks a bit more complicated than the previous one, so let's go through each argument step by step. First one is the name of our command, we'll use <tt>"sm_kdr"</tt>. Second one is a callback, but it has unknown tag <tt>ConCmd</tt>. In order to correctly call <tt>RegConsoleCmd</tt> we need to find how <tt>ConCmd</tt> is declared. Thankfully, we don't need to look hard, it's declared right above <tt>RegConsoleCmd</tt>:
<pawn>/**
* Called when a generic console command is invoked.
*
* @param client Index of the client, or 0 from the server.
* @param args Number of arguments that were in the argument string.
* @return An Action value. Not handling the command
* means that Source will report it as "not found."
*/
functag public Action:ConCmd(client, args);</pawn>
This is a function tag. What does it mean? It means that we need to define our own function that will have the same prototype (number of arguments, their tags and return tag) as the one of function tag. However, in this case, we don't need to (and can't) use the same name as in tag, that would result in error. We need to use our own name, let's use <tt>Command_KDR</tt>. Function tags doesn't require to use the same argument names as specified in declaration, but it's a good idea to use them, because they usually have the most meaning. So, all in all, it leads us to the following definition:
<pawn>public Action:Command_KDR(client, args)
{
}</pawn>
Now, if you've been following carefully, you should see that we have another unknown tag here - <tt>Action</tt>. Let's look how it's declared ('''core.inc'''):
<pawn>/**
* Specifies what to do after a hook completes.
*/
enum Action
{
Plugin_Continue = 0, /**< Continue with the original action */
Plugin_Changed = 1, /**< Inputs or outputs have been overridden with new values */
Plugin_Handled = 3, /**< Handle the action at the end (don't call it) */
Plugin_Stop = 4, /**< Immediately stop the hook chain and handle the original */
};</pawn>
It's an enumeration tag and in our callback it's up to us to decide which value to return. As you probably understood from reading all the info, SourceMod console commands are implemented as hooks between client and original server code. If we don't return anything and "let it slide" or return <tt>Plugin_Continue</tt>, the original command from client will reach the server and, since it's highly unlikely that there is <tt>sm_kdr</tt> command in the game, the message <tt>Unknown command "sm_kdr"</tt> will be printed to client's console. We don't want that, so let's modify our callback to return <tt>Plugin_Handled</tt>:
<pawn>public Action:Command_KDR(client, args)
{
return Plugin_Handled;
}</pawn>
It's a very common mistake to forget to return <tt>Plugin_Handled</tt> so our naive implementation is going to be not so naive after all! Now, after we finally understood how <tt>ConCmd</tt> tag works, it's time to move to the next argument of <tt>RegConsoleCmd</tt>. It is a string that will act like a description of our command. However, notice the <tt>=</tt> after argument name, it indicates that this argument is optional, we can skip it and empty string (<tt>""</tt>) will be used. And the last argument is flags and it's also optional. Command flags are used to change behavior of command, but for now default behavior is ok. Now we know the meaning of all arguments, let's make a call.
<pawn>RegConsoleCmd("sm_kdr", Command_KDR, "Displays the client their kills/deaths ratio.");</pawn>
Notice that we skipped flags because we want default behavior. Now let's see how the full command-related code looks like:
<pawn>public OnPluginStart()
{
RegConsoleCmd("sm_kdr", Command_KDR, "Displays the client their kills/deaths ratio.");
}

public Action:Command_KDR(client, args)
{
return Plugin_Handled;
}</pawn>
Why did we choose <tt>sm_kdr</tt> as the name of our command? It's handy because it will create convenient [[Commands_%28SourceMod_Scripting%29#Chat_Triggers|chat triggers]]. The skeleton of our command is ready, it is time to write the actual code for calculating KDR and displaying it to client. Notice that the first argument of our <tt>Command_KDR</tt> callback is <tt>client</tt>. When our callback is called, it will hold the index of client who called our command. We'll use this to find necessary information about client and to display that information back. First, let's find the number of kills, we'll use <tt>GetClientFrags</tt> function for that, it's declared in '''clients.inc''':
<pawn>/**
* Returns the client's frag count.
*
* @param client Player's index.
* @return Frag count.
* @error Invalid client index, client not in game, or no mod support.
*/
native GetClientFrags(client);</pawn>
It takes one argument - the client index and returns the number of frags. For the only argument of <tt>GetClientFrags</tt> we'll use <tt>client</tt> argument of our callback and we also need to store the return value so we'll create a local variable for that:
<pawn>new kills = GetClientFrags(client);</pawn>
By this time, it is assumed that you've learned how to read include files and find necessary information, so only links to online SourceMod API will be provided. Next, we need to find the number of client deaths, we'll use <tt>[http://docs.sourcemod.net/api/index.php?fastload=show&id=431& GetClientDeaths]</tt>:
<pawn>new deaths = GetClientDeaths(client);</pawn>
Now that we have both kills and deaths, let's find the ratio. Remember that by default all variables in SourcePawn act like integers, but we need the fractional part in this case. Another very important thing to remember is that a result of integer division is also an integer. So we need to convert both kills and deaths to floating point values and store the result in a floating point variable. <tt>[http://docs.sourcemod.net/api/index.php?fastload=show&id=705& float]</tt> function does the conversion.
<pawn>new Float:ratio = float(kills) / float(deaths);</pawn>
And now we only need to display the ratio, since our command can be called either via console or chat, it is good idea to display our info accordingly, so we'll use <tt>[http://docs.sourcemod.net/api/index.php?fastload=show&id=462& ReplyToCommand]</tt>. It's another [[Format_Class_Functions_(SourceMod_Scripting)|format class function]] and now we need to apply some formatting. In a nutshell, we pass the string which acts as a template for text and <tt>%</tt> sign and one-letter type identifier (which is called format specifier) for variable values to put inside that template. After that, we must pass the number of arguments that correspond to the number of format specifiers in our format string. Since we have a floating point number, the format specifier will be <tt>%f</tt>:
<pawn>ReplyToCommand(client, "Your KDR is: %f.", ratio);</pawn>
That's it! Now let's see the full code of our naive implementation:
<pawn>#include <sourcemod>

public Plugin:myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
version = "1.0",
url = "http://www.sourcemod.net/"
};

public OnPluginStart()
{
RegConsoleCmd("sm_kdr", Command_KDR, "Displays the client their kills/deaths ratio.");
}

public Action:Command_KDR(client, args)
{
new kills = GetClientFrags(client);
new deaths = GetClientDeaths(client);
new Float:ratio = float(kills) / float(deaths);
ReplyToCommand(client, "Your KDR is: %f.", ratio);
return Plugin_Handled;
}</pawn>
Compile and test this plugin and notice that something is wrong. We'll talk about it in the next section.

----

Talk:Introduction to sourceMod Plugins - Revision history

Asherkin: Created page with " ---- Below is FaTony's WIP rewrite of the command tutorial, it's been remove from the main page as it's incomplete and more confusing for new users--~~..."

Asherkin: Created page with " ----
Below is FaTony's WIP rewrite of the command tutorial, it's been remove from the main page as it's incomplete and more confusing for new users
--~~..."