AlliedModders Wiki - User contributions [en]

Timers (SourceMod Scripting)

2018-10-09T22:20:57Z

Hmmmmm: Update to transitional syntax

Timers in [[SourceMod]] are timed events that occur once or repeatedly at a given interval.

=Introduction=
Timers allow you to set an interval, a function to use as the event callback, and an optional Handle to pass through the callback. This is useful for saving data asynchronously.

All timer functions are in <tt>plugins/include/timers.inc</tt>.

=Basic Usage=
==One-Time Timers==
One-time timers are timers that only execute once. An example of a one-time timer might look like:

<pawn>public void OnPluginStart()
{
CreateTimer(5.0, LoadStuff);
}

public Action LoadStuff(Handle timer)
{
PrintToServer("Loading stuff!");
}</pawn>

This code will print "Loading stuff!" to the server console five seconds after the map loads. The return value has no meaning for one-time timers.

==Repeatable Timers==
Repeatable timers execute infinitely many times, once every interval. Based on the return value, they either continue or cancel.

For example, say you want to display a message five times, once every three seconds:
<pawn>
void someFunction()
{
CreateTimer(3.0, Timer_PrintMessageFiveTimes, _, TIMER_REPEAT);
}

public Action Timer_PrintMessageFiveTimes(Handle timer)
{
// Create a global variable visible only in the local scope (this function).
static int numPrinted = 0;

if (numPrinted >= 5)
{
numPrinted = 0;
return Plugin_Stop;
}

PrintToServer("Warning! This is a message.");
numPrinted++;

return Plugin_Continue;
}</pawn>

Note that <tt>Plugin_Stop</tt> stops the timer, and <tt>Plugin_Continue</tt> allows it to continue repeating.

=Passing Data=
==Simple Values==
As mentioned earlier, timers let you pass values on to the callback function. This value can be any type. For example, let's say we want to print a message to a player fifteen seconds after they connect. However, we want to cancel the timer if the player disconnects. Implementing this is very easy:

<pawn>
Handle WelcomeTimers[MAXPLAYERS+1];

public void OnClientPutInServer(int client)
{
WelcomeTimers[client] = CreateTimer(15.0, WelcomePlayer, client);
}

public void OnClientDisconnect(int client)
{
if (WelcomeTimers[client] != null)
{
KillTimer(WelcomeTimers[client]);
WelcomeTimers[client] = null;
}
}

public Action WelcomePlayer(Handle timer, any client)
{
PrintToConsole(client, "Welcome to the server!");
WelcomeTimers[client] = null;
}</pawn>

Another example without using handles is to use either UserID or ClientSerial (which is unique to each player):

<pawn>
public void OnClientPutInServer(int client)
{
CreateTimer(15.0, WelcomePlayer, GetClientSerial(client)); // You could also use GetClientUserId(client)
}

public Action WelcomePlayer(Handle timer, any serial)
{
int client = GetClientFromSerial(serial); // Validate the client serial

if (client == 0) // The serial is no longer valid, the player must have disconnected
{
return Plugin_Stop;
}

PrintToConsole(client, "Welcome to the server!");
}</pawn>
If you want to close or cancel a timer when a client disconnects, then use the first example with handles.

==Handles==
If you want to pass a Handle as a value, you have the option of using <tt>TIMER_DATA_HNDL_CLOSE</tt>, which will automatically call <tt>CloseHandle()</tt> for you once the timer dies.

==Data Packs==
Data packs are packable structures that can be used to hold asynchronous data (data that must be saved and unpacked for later). They are especially useful for timers, and thus there exists a helper function, called <tt>CreateDataTimer()</tt>, which creates a timer using a data pack handle. The handle is created and closed automatically for you.

The above example could be rewritten as:
<pawn>
Handle WelcomeTimers[MAXPLAYERS+1];

public void OnClientPutInServer(int client)
{
DataPack pack;
WelcomeTimers[client] = CreateDataTimer(15.0, WelcomePlayer, pack);
pack.WriteCell(client);
pack.WriteString("Welcome to the server!");
}

public void OnClientDisconnect(int client)
{
if (WelcomeTimers[client] != null)
{
KillTimer(WelcomeTimers[client]);
WelcomeTimers[client] = null;
}
}

public Action WelcomePlayer(Handle timer, DataPack pack)
{
char str[128];
int client;

/* Set to the beginning and unpack it */
pack.Reset();
client = pack.ReadCell();
pack.ReadString(str, sizeof(str));
PrintToConsole(client, "%s", str);
WelcomeTimers[client] = null;
}</pawn>

=Notes=
==Accuracy==
The smallest possible interval is 0.1 seconds. Timers have high precision (floating point) but low accuracy, as the current time is based on the in-game tick count, not the system clock. This has two implications:
*If the server is paused (not ticking or hibernating), timers will not run.
*The server will not always tick at an exact interval.

For example, a 1.234 second interval timer starting from time <tt>t</tt> might not tick until <tt>t+1.242</tt> at a tickrate of 66 ticks per second.

==Timer Death==
All timers are guaranteed to die either by:
*<tt>CloseHandle()</tt> being called (or on plugin unload);
*<tt>KillTimer()</tt> being called;
*<tt>Plugin_Stop</tt> being returned from a repeatable timer;
*<tt>TriggerTimer()</tt> being called on a one-time timer;
*Execution of a one-time timer finishes.

When a timer dies, if <tt>TIMER_DATA_HNDL_CLOSE</tt> is set, the Handle will always be closed with the permissions that <tt>CloseHandle()</tt> uses by default. Since timers cannot be cloned, there should be no ownership issues.

==Changing Intervals==
The interval of a timer cannot be changed as of this writing. The timer must be killed and a new one created.

==AMX Mod X==
Unlike [[AMX Mod X]]'s <tt>set_task</tt> function, you cannot pass arrays using <tt>CreateTimer</tt>. To accomplish this, you should use the data pack functionality explained above.

Similarly, there are no flags for counted repeats (non-infinite loops) or timers based on the map start or end. These must be done manually.

=External Links=
*[http://www.sourcemod.net/devlog/?p=130 On Timer Design, Part 3] (SourceMod DevLog)
*[http://www.sourcemod.net/devlog/?p=119 On Timer Design, Part 2] (SourceMod DevLog)
*[http://www.sourcemod.net/devlog/?p=118 On Timer Design, Part 1] (SourceMod DevLog)

[[Category:SourceMod Scripting]]

{{LanguageSwitch}}

Menus Step By Step (SourceMod Scripting)

2018-10-02T00:12:32Z

Hmmmmm: GetInfo -> GetItem

The SourceMod [[Menu API (SourceMod)|Menu API]] is fairly useful for displaying an information panel, a menu, or a vote to users. This document talks specifically about menus and how to create one.

== The working menu example ==

This is the working code example that we'll be talking about in the upcoming sections. If you need to, you can come back and look at it as you read the rest of this page.

We will be using PrintToServer to print text to the server console as we run through the events.

Usage of the [[Translations (SourceMod Scripting)|Translations]] system is highly recommended and will be used in this example.

<pawn>#define CHOICE1 "#choice1"
#define CHOICE2 "#choice2"
#define CHOICE3 "#choice3"

public void OnPluginStart()
{
LoadTranslations("menu_test.phrases");
RegConsoleCmd("menu_test1", Menu_Test1);
}

public int MenuHandler1(Menu menu, MenuAction action, int param1, int param2)
{
switch(action)
{
case MenuAction_Start:
{
PrintToServer("Displaying menu");
}

case MenuAction_Display:
{
char buffer[255];
Format(buffer, sizeof(buffer), "%T", "Vote Nextmap", param1);

Panel panel = view_as<Panel>(param2);
panel.SetTitle(buffer);
PrintToServer("Client %d was sent menu with panel %x", param1, param2);
}

case MenuAction_Select:
{
char info[32];
menu.GetItem(param2, info, sizeof(info));
if (StrEqual(info, CHOICE3))
{
PrintToServer("Client %d somehow selected %s despite it being disabled", param1, info);
}
else
{
PrintToServer("Client %d selected %s", param1, info);
}
}

case MenuAction_Cancel:
{
PrintToServer("Client %d's menu was cancelled for reason %d", param1, param2);
}

case MenuAction_End:
{
delete menu;
}

case MenuAction_DrawItem:
{
int style;
char info[32];
menu.GetItem(param2, info, sizeof(info), style);

if (StrEqual(info, CHOICE3))
{
return ITEMDRAW_DISABLED;
}
else
{
return style;
}
}

case MenuAction_DisplayItem:
{
char info[32];
menu.GetItem(param2, info, sizeof(info));

char display[64];

if (StrEqual(info, CHOICE3))
{
Format(display, sizeof(display), "%T", "Choice 3", param1);
return RedrawMenuItem(display);
}
}
}

return 0;
}

public Action Menu_Test1(int client, int args)
{
Menu menu = new Menu(MenuHandler1, MENU_ACTIONS_ALL);
menu.SetTitle("%T", "Menu Title", LANG_SERVER);
menu.AddItem(CHOICE1, "Choice 1");
menu.AddItem(CHOICE2, "Choice 2");
menu.AddItem(CHOICE3, "Choice 3");
menu.ExitButton = false;
menu.Display(client, 20);

return Plugin_Handled;
}</pawn>

The translation file that goes with it... addons/sourcemod/translations/menu_test.phrases.txt

<pre>"Phrases"
{
"Choice 3"
{
"en" "Choice Translated"
}

"Menu Title"
{
"en" "Menu Title Translated"
}
}</pre>

== Step by Step ==

=== OnPluginStart ===

<pawn>public void OnPluginStart()
{
LoadTranslations("menu_test.phrases");
RegConsoleCmd("menu_test1", Menu_Test1);
}</pawn>

This block is here to register the command /menu_test1 so that this menu can be tested.

This block is beyond the scope of this page. See: [[Introduction to SourceMod Plugins#Plugin Structure|Plugin Structure]] for OnPluginStart, [[Translations (SourceMod Scripting)|Translations]] for LoadTranslations, and [[Commands_(SourceMod_Scripting)|Commands]] for RegConsoleCmd.

=== Menu_Test1 ===

Menu_Test1 is a ConCmd, which is beyond the scope of this page. See: [[Commands (SourceMod Scripting)|Commands]] for more details on that. We're going to be talking about what's in it.

==== Menu ====

<pawn> Menu menu = new Menu(MenuHandler1, MENU_ACTIONS_ALL);</pawn>

Menu takes two arguments.

The first is a function that matches the [https://sm.alliedmods.net/new-api/menus/MenuHandler MenuHandler] callback signature.

The second is a bitmask of which MenuAction events we are going to handle in our MenuHandler. There are 7 that apply to standard menus:
* MenuAction_Start - Called once when a menu is displayed
* MenuAction_Display - Called once for each client a menu is displayed to
* MenuAction_Select - Called when a client makes a selection from the menu that isn't Previous, Next, Back, or Exit.
* MenuAction_Cancel - Called when a client closes a menu or it is closed on them
* MenuAction_End - Called once when all clients have closed the menu
* MenuAction_DrawItem - Called once for each item for each user a menu is displayed to. Can change the menu item style.
* MenuAction_DisplayIitem. - Called once for each item for each user a menu is displayed to. Can change the menu item text.

These will be discussed in more detail in the MenuHandler1 section.

Of those 7, 3 are called whether you specify them or not: MenuAction_Select, MenuAction_Cancel, and MenuAction_End.

MENU_ACTIONS_DEFAULT sets just the 3 required fields, while MENU_ACTIONS_ALL specifies all 10 actions (including the 3 vote actions).

To specify just a few of them, you can do this:

<pawn> Menu menu = new Menu(MenuHandler1, MenuAction_Start|MenuAction_Select|MenuAction_Cancel|MenuAction_End);</pawn>

==== menu.SetTitle ====
<pawn> menu.SetTitle("%T", "Menu Title", LANG_SERVER);</pawn>

Sets the menu's title. This example uses the translation system and the server's default language. This isn't strictly necessary as we will set the menu title again later.

==== menu.AddItem ====

<pawn> menu.AddItem(CHOICE1, "Choice 1");
menu.AddItem(CHOICE2, "Choice 2");
menu.AddItem(CHOICE3, "Choice 3");</pawn>

A menu isn't useful without something in it!
menu.AddItem has 2 required arguments and one optional argument.

The 2 required arguments are:

The Info string, and the Display string.

The Info String is a string that is used to uniquely identify this menu item. It is never displayed to the user, but is used in various callbacks.

The Display String is the default text to be used for this item on the menu. It can be changed via the menu's MenuAction_DisplayItem callback.

The optional argument is the menu's item draw style. It can be one of these values:
* ITEMDRAW_DEFAULT - Displays text as normal.
* ITEMDRAW_DISABLED - Item is displayed and has a number, but can't be selected.
* ITEMDRAW_RAWLINE - Item is displayed, but doesn't have a number assigned to it and thus can't be selected
* ITEMDRAW_NOTEXT - Draws an item with no text. Not very useful.
* ITEMDRAW_SPACER - Item is blank, but has a number. Can't be selected.
* ITEMDRAW_IGNORE - Item is blank with no number. Can't be selected.
* ITEMDRAW_CONTROL - Don't use this one. It's used for the items SourceMod automatically adds.

Be aware that if your CreateMenu second argument includes MenuAction_DrawItem or MENU_ACTIONS_ALL and you don't actually implement the MenuAction_DrawItem callback (or implement it and don't return the current item's style if you don't change it), your style here will be completely ignored.

==== menu.ExitButton ====
<pawn> menu.ExitButton = false;</pawn>

Defaults to true.

It set to false, the menu won't have an exit button.

==== menu.ExitBackButton ====
<pawn> menu.ExitBackButton = false;</pawn>

(This isn't in the code above, but it should be mentioned)

Defaults to false.

Should only be used if the menu is a submenu, with the menu set up to check the cancel reason to see if the ExitBack action was used.

If set to true, replaces the Exit item with the Back item. The Back item still cancels the menu, but has a separate cancel reason.

This can be used to dynamically set if a menu is being called as its own menu or as a submenu.

==== menu.Display ====
<pawn> menu.Display(client, 20);</pawn>

DisplayMenu takes 2 arguments:

A Menu handle, a client index, and the amount of time in seconds to show the menu.

If you want the menu to show forever, pass MENU_TIME_FOREVER as the third argument.

=== MenuHandler1 ===
<pawn>public int MenuHandler1(Menu menu, MenuAction action, int param1, int param2)</pawn>

MenuHandler1 is a function whose signature matches the MenuHandler callback. It can be named something other than MenuHandler1. It must always be public and it will always have these arguments: Handle, MenuAction, cell, and cell in that order.

The Handle argument is always the menu that called the handler.

The MenuAction argument is always one of 7 actions for a standard menu. They are: MenuAction_Start, MenuAction_Display, MenuAction_Select, MenuAction_Cancel, MenuAction_End, MenuAction_DrawItem, and MenuAction_DisplayIitem. We will discuss each of these as we reach their code.

The two cell arguments meaning depend on the MenuAction argument. '''A common mistake is to assume param1 is the client.''' This is incorrect for MenuAction_Start, MenuAction_End, MenuAction_VoteEnd, MenuAction_VoteStart, and MenuAction_VoteCancel.

==== MenuAction_Start ====

<pawn> case MenuAction_Start:
{
PrintToServer("Displaying menu");
}</pawn>

* param1: not set
* param2: not set
* return: 0 (or don't return)

MenuAction_Start doesn't set param1 and param2. It is fired when the menu is displayed to one or more users using DisplayMenu, DisplayMenuAtItem, VoteMenu, or VoteMenuToAll.

==== MenuAction_Display ====

<pawn> case MenuAction_Display:
{
char buffer[255];
Format(buffer, sizeof(buffer), "%T", "Vote Nextmap", param1);

Panel panel = view_as<Panel>(param2);
panel.SetTitle(buffer);
PrintToServer("Client %d was sent menu with panel %x", param1, param2);
}</pawn>

* param1: client index
* param2: MenuPanel Handle
* return: 0 (or don't return)

MenuAction_Display is called once for each user a menu is displayed to. param1 is the client, param2 is the MenuPanel handle.

SetPanelTitle is used to change the menu's title based on the language of the user viewing it using the Translations system. Previous versions of this guide suggested using SetMenuTitle. This is a ''bad'' idea, as it changes the title globally.

==== MenuAction_Select ====
<pawn> case MenuAction_Select:
{
char info[32];
menu.GetItem(param2, info, sizeof(info));
if (StrEqual(info, CHOICE3))
{
PrintToServer("Client %d somehow selected %s despite it being disabled", param1, info);
}
else
{
PrintToServer("Client %d selected %s", param1, info);
}
}</pawn>

* param1: client index
* param2: item number for use with GetMenuItem
* return: 0 (or don't return)

MenuAction_Select is called when a user selects a non-control item on the menu (something added using AddMenuItem). param1 is the client, param2 is the menu position of the item the client selected.

Using the item position to check which item was selected is a bad idea, as item position is brittle and will break things if AddMenuItem or InsertMenuItem is used. It is recommended that you instead use the Menu item's info string, as done in the code above.

GetMenuItem is used here to fetch the info string.

==== MenuAction_Cancel ====

case MenuAction_Cancel:
{
PrintToServer("Client %d's menu was cancelled for reason %d", param1, param2);
}

* param1: client index
* param2: MenuCancel reason
* return: 0 (or don't return)

MenuAction_Cancel is called whenever a user closes a menu or it is closed for them for another reason. param1 is the client, param2 is the close reason.

The close reasons you can receive are:

* MenuCancel_Disconnected - The client got disconnected from the server.
* MenuCancel_Interrupted - Another menu opened, automatically closing our menu.
* MenuCancel_Exit - The client selected Exit. Not called if SetMenuExitBack was set to true. Not called if SetMenuExit was set to false.
* MenuCancel_NoDisplay - Our menu never displayed to the client for whatever reason.
* MenuCancel_Timeout - The menu timed out. Not called if the menu time was MENU_TIME_FOREVER.
* MenuCancel_ExitBack - The client selected Back. Only called if SetMenuExitBack has been called and set to true before the menu was sent. Not called if SetMenuExit was set to false.

==== MenuAction_End ====
<pawn> case MenuAction_End:
{
delete menu;
}</pawn>

* param1: MenuEnd reason
* param2: If param1 is MenuEnd_Cancelled, the MenuCancel reason
* return: 0 (or don't return)

MenuAction_End is called when ''all'' clients have closed a menu or vote. For menus that are not going to be redisplayed, it is required that you call CloseHandle on the menu here.

The parameters are rarely used in MenuAction_End. param1 is the menu end reason. param2 depends on param1.

The end reasons you can receive for normal menus are:

* MenuEnd_Selected - The menu closed because an item was selected (MenuAction_Select was fired)
* MenuEnd_Cancelled - The menu was cancelled (MenuAction_Cancel was fired), cancel reason is in param2; cancel reason can be any of the ones listed in MenuAction_Cancel except MenuCancel_Exit or MenuCancel_ExitBack
* MenuEnd_Exit - The menu was exited via the Exit item (MenuAction_Cancel was fired with param2 set to MenuCancel_Exit)
* MenuEnd_ExitBack - The menu was exited via the ExitBack item (MenuAction_Cancel was fired with param 2 set to MenuCancel_ExitBack)

Note: You do '''not''' have the client index during this callback, so it's far too late to do anything useful with this information.

==== MenuAction_DrawItem ====
<pawn> case MenuAction_DrawItem:
{
int style;
char info[32];
menu.GetItem(param2, info, sizeof(info), style);

if (StrEqual(info, CHOICE3))
{
return ITEMDRAW_DISABLED;
}
else
{
return style;
}
}</pawn>

* param1: client index
* param2: item number for use with GetMenuItem
* return: new ITEMDRAW properties or style from GetMenuItem. Since 0 is ITEMDRAW_DEFAULT, returning 0 clears all styles for this item.

MenuAction_DrawItem is called once for each item on the menu for each user. You can manipulate its draw style here. param1 is the client, param2 is the menu position.

Using the item position to check which item was selected is a bad idea, as item position is brittle and will break things if AddMenuItem or InsertMenuItem is used. It is recommended that you instead use the Menu item's info string, as done in the code above.

GetMenuItem is used here to fetch the info string and menu style.

You should return the style you want the menu item to have. In our example, if client 1 is viewing the menu, we want CHOICE3 to be disabled.

the return value is a bitfield, so to apply multiple styles, you do something like this:

return ITEMDRAW_NOTEXT | ITEMDRAW_SPACER;

'''Failing to return the current item's style if you don't change the style is a programmer error.'''

==== MenuAction_DisplayItem ====

<pawn> case MenuAction_DisplayItem:
{
char info[32];
menu.GetItem(param2, info, sizeof(info));

char display[64];

if (StrEqual(info, CHOICE3))
{
Format(display, sizeof(display), "%T", "Choice 3", param1);
return RedrawMenuItem(display);
}
}</pawn>

* param1: client index
* param2: item number for use with GetMenuItem
* return: return value from RedrawMenuItem or 0 for no change

MenuAction_DrawItem is called once for each item on the menu for each user. You can manipulate its text here. param1 is the client, param2 is the menu position.

This callback is intended for use with the Translation system.

Using the item position to check which item was selected is a bad idea, as item position is brittle and will break things if AddMenuItem or InsertMenuItem is used. It is recommended that you instead use the Menu item's info string, as done in the code above.

GetMenuItem is used here to fetch the info string.

Once we have the info string, we compare our item to it and apply the appropriate translation string.

If we change an item, we have to call RedrawMenuItem and return the value it returns. If we do not change an item, we must return 0.

==== return ====
<pawn> return 0;</pawn>

If you handle MenuAction_DrawItem or MenuAction_DisplayItem, you will get the following warning if you fail to return 0 after the switch block:

<code>warning 209: function "MenuHandler1" should return a value</code>

This is because MenuAction_DrawItem and MenuAction_DisplayItem have return values, while the other actions only return 0.

== The End ==
Hopefully this walk through a simple menu helped you understand why each call is being made where. Menus have some options that we didn't explore here, such as disabling pagination (which is enabled by default). You may want to refer to the main Menu documentation for more details.

Writing Extensions

2018-01-31T14:54:41Z

Hmmmmm: Updated sourcepawn sections to new syntax

SourceMod's Extension System is a powerful way to greatly enhance the flexibility of your SourceMod plugins. You can take full advantage of SourceMod's Core, using the interfaces it provides, to create C++ plugins, plugin events, plugin native functions, and shared interfaces. Extensions can also hook into Metamod:Source.

This article goes into the details of creating a SourceMod Extension. Knowledge of C++ is required.

=SDK Structure=
First, download the [[SourceMod SDK]] from the [https://github.com/alliedmodders/sourcemod/releases SourceMod github], and one of the SDKs from the [https://github.com/alliedmodders/hl2sdk hl2sdk github]. The directory structure should contain these folders:
<code>
* hl2sdk-something - One of the HL2 SDKs
* sourcemod-version - The sourcemod package
** extensions - Sourcemod Extensions code
*** curl - Source code to the cURL extension
*** geoip - Source code to the GeoIP extension
*** mysql - Source code to the MySQL extension
** plugins - Source code to all of SourceMod's plugins
*** include - The include files which document plugin API
** public - Interface files for SourceMod's Core Interfaces
*** extensions - Interfaces that are provided by extensions
*** '''sample_ext''' - The Sample Extension SDK
**** extension.cpp - Sample C++ plugin
**** extension.h - Sample C++ header file
**** Makefile - Sample C++ plugin compiler
**** smsdk_config.h - Sample C++ plugin settings
** sourcepawn - The include/interface files for SourcePawn
*** compiler - The SourcePawn Compiler
</code>

=Starting an Extension=
For simplicity, this article will assume you are using the SDK base files. Navigate to <code>extensions/public/sample_ext</code>, and ensure that you can compile your code. If using the command line, <code>make</code> should do this, if using Visual Studio, see [[#Setting up Visual Studio|Setting up Visual Studio]].

The first step of creating your extension is to configure it. Open the <tt>smsdk_config.h</tt> file and edit each of the following defines. Use the information below to guide you.
<code>
*SMEXT_CONF_NAME - The general name for your Extension (should be short).
*SMEXT_CONF_DESCRIPTION - A short description of what your extension does.
*SMEXT_CONF_VERSION - A version number string. By convention, SourceMod uses the four set build number notation, so build 1.2.3.4 means:
**1 is the "Major" release version.
**2 is the "Minor" release version.
**3 is the "Maintenance" or "Revision" version.
**4 is the "Build," usually an internal source control number.
*SMEXT_CONF_AUTHOR - Your name (or whoever/whatever authored the plugin).
*SMEXT_CONF_URL - The URL/homepage of this extension.
*SMEXT_CONF_LOGTAG - The logtag your extension will use for SourceMod logging. By convention, try to keep this under ten characters or so, and to make it all caps.
*SMEXT_CONF_LICENSE - Right now, the SourceMod Dev Team mandates that 3rd party extensions must be under an Open Source license. Putting a license abbreviation or very short message here is appropriate. For more information, see [https://www.sourcemod.net/license.php the SourceMod license].
*SMEXT_CONF_DATESTRING - You do not need to modify this.
</code>
If your plugin requires using SourceHook or Metamod:Source, uncomment this line:
<code>#define SMEXT_CONF_METAMOD</code>

Next, you should change the name of your extension. By convention, your extension's class name should start with a capital letter.
* First, open <code>extension.h</code> and change "Sample" in this line:
<cpp>class Sample : public SDKExtension</cpp>
* Next, open <code>extension.cpp</code> change these two lines:
<cpp>Sample g_Sample;
SMEXT_LINK(&g_Sample);</cpp>

==Visual Studio Users==
Make sure you change the name of your <tt>.dll</tt> file. The naming convention for SourceMod extensions is <tt>name.ext.dll</tt>, where <tt>name</tt> is a short name for your extension. You are free to change this, but it is highly recommended that you keep the <tt>.ext.dll</tt> intact.

You can do this by going to <tt>Project</tt> -> <tt>Properties</tt> -> <tt>Configuration Properties</tt> -> <tt>Linker</tt> -> <tt>General</tt>. Set the <tt>Output File</tt> option appropriately.

==Linux Users==
Simply edit the <tt>Makefile</tt> and change the <tt>BINARY</tt> line near the top. Make sure you do not add any trailing spaces at the end of the name, or the build won't come out right.

You should now be able to compile a blank extension!

=Creating Native Functions=
''Main article: [[Natives (SourceMod Development)]]''

Most of the time, an extension exists to add "native functions" to the plugin system. Native functions are simply the functions that plugins can use in SourceMod. They are coded in C++ and have a short prototype declaration in an include file.

==Prototyping==
The first step to creating a native is to <tt>spec it</tt>, or <tt>prototype</tt> it. This is a simple but often time consuming process, but if you get in the habit of it, your documentation will be much better. Let's first create a very simply native. Here is a prototype for it, which we will place in <tt>sample.inc</tt>:
<pawn>/**
* Returns the square of a number.
*
* @param num Number to square.
* @return The square of num.
*/
native int SquareNumber(num);</pawn>

The <tt>native</tt> keyword tells the compiler that this function exists in an outside source. The comment style is similar to [http://www.stack.nl/~dimitri/doxygen/ doxygen] or [http://java.sun.com/j2se/javadoc/ Javadoc], and is preferred by the SourceMod Development Team.

==Implementing==
Now that our function is documented, it's time to create it! Each native function is bound to a C++ function. The prototype for this function looks like:
<cpp>cell_t Function(IPluginContext *pContext, const cell_t *params);</cpp>

A quick explanation of these types:
*<tt>cell_t</tt> - This is a 32bit signed integer, the generic data type for Pawn.
*<tt>IPluginContext</tt> - This interface provides Virtual Machine functions for retrieving or modifying memory in the plugin.
*<tt>params</tt> - This is the "stack" of parameters that the plugin passed. It is an array from [0..N] where 0 contains N. This means <tt>params[0]</tt> contains the number of arguments passed to the native.
**For example, if one parameter was passed, and the parameter is 25:
***<tt>params[0]</tt> == 1
***<tt>params[1]</tt> == 25
**Even though it tells you how many parameters are passed, you do not need to verify this number. The compiler will always pass the correct number of parameters in. The only time you need to verify it is for backwards compatibility or variable parameter lists, which will be discussed later.

Now, let's write our native function:
<cpp>cell_t SquareNumber(IPluginContext *pContext, const cell_t *params)
{
cell_t number = params[1];
return number * number;
}</cpp>

==Binding==
Now, the final step is to bind our native. Natives are bound in ''native lists''. Each list must be terminated by a <tt>NULL</tt> bind. Example:
<cpp>const sp_nativeinfo_t MyNatives[] =
{
{"SquareNumber", SquareNumber},
{NULL, NULL},
};</cpp>

The first column/member is a string containing the name you've assigned to the native. The second column/member is the C++ function you're binding to. Here, both contain the same name, but it is certainly possible to bind a function to any valid Pawn function name, and likewise, you can bind one function to more than one name.

Lastly, you must tell Core about your native list. There are two places that are good to do this. Whichever you choose, you must uncomment the function in <tt>extension.h</tt> and implement it in <tt>extension.cpp</tt>.
*<tt>SDK_OnLoad</tt> - This is called when your extension is first loaded. If you do not require any outside interfaces, it is safe to add natives here.
*<tt>SDK_OnAllLoaded</tt> - This is called when all extensions have been loaded. This is generally a better place to add natives.

Let's say we choose <tt>SDK_OnAllLoaded</tt>, we'd then have code like this:
<cpp>void Sample::SDK_OnAllLoaded()
{
sharesys->AddNatives(myself, MyNatives);
}</cpp>
''Note: <tt>myself</tt> is a global variable declared in the SDK. It is a pointer that identifies your extension.''

For more information on writing natives, see [[Natives (SourceMod Development)]].

=Creating Events/Forwards=
Events are an integral part to SourceMod. An Event is formally called a ''Forward''. Forwards are functions inside a plugin which are not called by the plugin itself, but are triggered from an external source. For example, <tt>OnClientConnect</tt> is a forward which is triggered when a player connects to a server.

There are two major types of forwards:
*'''Managed''': This forward is global and has a name. To use this forward, the function must be declared as <tt>public</tt> inside the user's script. Any plugin having this public function will receive the event.
*'''Unmanaged''': This forward is private in nature. For example, the <tt>HookUserMessage</tt> native lets users specify a function to be called when a specific user message is sent. This is done with an unmanaged forward, and adding functions to this forward is not automatic. In general, function calls for unmanaged forwards are not public, although they can be.

''Note: To enable the Forward interface, you must uncomment the definition <tt>SMEXT_ENABLE_FORWARDSYS</tt> in smsdk_config.h.''
==Managed Forwards==
Let's say we want to create a forward that will be called when a player uses say chat. For simplicity, let's assume you already have a function that tells you when a player says say chat. We will just be creating the forward for it.

As we did before, first let's prototype our global forward. In our include file, we add this:
<pawn>/**
* @brief Called whenever a client says something in chat.
*
* @param client Index of the client.
* @param text String containing the say text.
* @return Plugin_Handled to block text from printing, Plugin_Continue otherwise.
*/
forward Action OnPlayerSayChat(int client, const char[] text);</pawn>

The <tt>forward</tt> keyword tells the compiler that any function having this name must be declared exactly the same. In a plugin, this would

The next step is to declare your forward somewhere at the top of your <tt>extension.cpp</tt> file. This will look like:
<cpp>IForward *g_pSayChat = NULL</cpp>

Next, re-using our code from above, let's create this forward in <tt>SDK_OnAllLoaded</tt>:
<cpp>void Sample::SDK_OnAllLoaded()
{
sharesys->AddNatives(myself, MyNatives);
g_pSayChat = forwards->CreateForward("OnPlayerSayChat", ET_Event, 2, NULL, Param_Cell, Param_String);
}</cpp>

Explanation of parameters:
*<tt>"OnPlayerSayChat"</tt> - The name of our forward.
*<tt>ET_Event</tt> - Since forwards can execute multiple functions in multiple scripts, this is one of the ways of specifying what to do with the return value of each function. <tt>ET_Event</tt> means "return the highest value, do not allow stops." A stop refers to <tt>Pl_Stop</tt>, which lets a plugin block the rest of the event chain.
*<tt>2</tt> - This is the number of parameters our forward will have.
*<tt>NULL</tt> - Not used in our example. This lets you pass parameters by array rather than variable arguments.
*<tt>Param_Cell</tt> - The first parameter is a cell (integer).
*<tt>Param_String</tt> - The second parameter is a string.

Now, we write a quick function in our module to call this forward:
<cpp>/** Fires the say chat event in plugins. Returns true to allow the text, false to block. */
bool FireChatEvent(int client, const char *text)
{
if (!g_pSayChat)
{
return true;
}

cell_t result = 0;
g_pSayChat->PushCell(client);
g_pSayChat->PushString(text);
g_pSayChat->Execute(&result);

if (result == Pl_Handled)
{
return false;
}

return true;
}</cpp>

As you can see, this was pretty simple. Each parameter is "pushed" one at a time, in ascending order. First we push the client index as a cell, then the text as a string. Once done, we execute, and the value will be returned by reference.

Lastly, there is a caveat. Unlike natives, SourceMod does not automatically clean up forwards for us when are done. We have to make sure we destroy them. Uncomment <tt>SDK_OnUnload</tt> from <tt>extension.h</tt> and implement it like so:
<cpp>void Sample::SDK_OnUnload()
{
forwards->ReleaseForward(g_pSayChat);
}</cpp>

==Unmanaged Forwards==
Now things get a bit more complicated. However, unmanaged forwards are essentially the same -- they just give you more flexibility. Let's consider the managed example with a new twist. We want to let users add and remove hooks from their plugins, rather than having one global forward. The standard way to do this is with ''function IDs''.

Example prototype:
<pawn>typedef SayChatHook = function Action (int client, const char[] text);

native void AddSayChatHook(SayChatHook hook);
native void RemoveSayChatHook(SayChatHook hook);</pawn>

The <tt>funcenum</tt> syntax lets you define all the valid prototypes for your hook. In this example, the only valid method is a function declared like this (only MyHook can be changed):
<pawn>Action MyHook(int client, const char[] text)</pawn>

How do we make such a beast? The first step is setting up our forward.
<cpp>IChangeableForward *g_pSayChat = NULL;
/* ... */
void Sample::SDK_OnAllLoaded()
{
g_pSayChat = forwards->CreateForwardEx(NULL, ET_Hook, 2, NULL, Param_Cell, Param_String);
}</cpp>

Notice two big differences. We now use <tt>IChangeableForward</tt> instead of <tt>IForward</tt>, and we use <tt>CreateForwardEx</tt> instead. The initial first parameter specifies a name for our forward - we're going to ignore this.

Now, we need to create our natives. These will be fairly simple:
<cpp>cell_t AddSayChatHook(IPluginContext *pContext, const cell_t *params)
{
g_pSayChat->AddFunction(pContext, static_cast<funcid_t>(params[1]));
return 1;
}

cell_t RemoveSayChatHook(IPluginContext *pContext, const cell_t *params)
{
IPluginFunction *pFunction = pContext->GetFunctionById(static_cast<funcid_t>(params[1]));
g_pSayChat->RemoveFunction(pFunction);
return 1;
}</cpp>
''Note: These natives must be added -- that step is removed here and explained earlier.''

You do not need to worry about a plugin unloading - Core will automatically remove the functions for you. Since an <tt>IChangeableForward</tt> is also an <tt>IForward</tt>, the <tt>FireChatEvent</tt> function from earlier does not need to change. We're done!

==Creating Interfaces==
Do you want your extension to share an interface? If so, first you should create an ''interface file''. This file should contain everything your interface needs - this way other authors can easily reference it. Your interface must inherit the <tt>SMInterface</tt> class. It must also declare two global macros that uniquely identify your interface. It must also implement two functions: <tt>GetInterfaceName</tt> and <tt>GetInterfaceVersion</tt>.

The two defines must start with <tt>SMINTERFACE_</tt> and end with <tt>_NAME</tt> and <tt>_VERSION</tt> respectively. The first must be a string and the second must be an unsigned integer. This integer represents your interface's version number. While you are free to use it however you please, by default it should be linearly increased. If you make breaking changes or change the versioning scheme, you must overload the <tt>IsVersionCompat</tt> function in <tt>SMInterface</tt>.

Example:
<cpp>#ifndef _INCLUDE_MYINTERFACE_FILE_H_
#define _INCLUDE_MYINTERFACE_FILE_H_

#include <IShareSys.h>

#define SMINTERFACE_MYINTERFACE_NAME "IMyInterface"
#define SMINTERFACE_MYINTERFACE_VERSION 1

class IMyInterface : public SourceMod::SMInterface
{
public:
virtual const char *GetInterfaceName()
{
return SMINTERFACE_MYINTERFACE_NAME;
}
virtual unsigned int GetInterfaceVersion()
{
return SMINTERFACE_MYINTERFACE_VERSION;
}
public:
/**
* @brief This function does nothing.
*/
virtual void DoNothingAtAll() =0;
};

#endif //_INCLUDE_MYINTERFACE_FILE_H_</cpp>

Notice, of course, that our interface is ''pure virtual''. This means it must be implemented in the extension. Assuming you know C++, this should be fairly straight forward, so let's skip right to how to add this interface to the SourceMod shared system:
<cpp>bool Sample::SDK_OnLoad(char *error, size_t err_max, bool late)
{
sharesys->AddInterface(myself, &g_MyInterface);
return true;
}</cpp>
''Note: We do this in <tt>SDK_OnLoad()</tT> instead of <tt>SDK_OnAllLoaded()</tt>. Otherwise, an extension might try to search for your interface during <tt>SDK_OnAllLoaded()</tt>, and it might fail depending on the load order.''

That simple? Yup! Now other extensions can use your interface.

=Using Interfaces/Other Extensions=
There are a variety of interfaces that are available, but not loaded by default in the Extension SDK. These interfaces can be retrieved and used in your extension.

==Core Interfaces==
If they are provided by Core, getting them is very simple. Many interfaces can simply be uncommented in <tt>smsdk_config.h</tt> and they will become usable. See the "Available Interfaces" list below for the exposure list.

Otherwise, most of the <tt>.h</tt> interface files in the root of the <tt>public</tt> folder in the SDK are Core interfaces. For example, code to use the IPluginManager interface might look like this:
<cpp>#include <IPluginSys.h>

IPluginManager *g_pPlugins = NULL;

bool Sample::SDK_OnLoad(char *error, size_t err_max, bool late)
{
SM_GET_IFACE(PLUGINSYSTEM, g_pPlugins);
return true;
}</cpp>

Where did we get <tt>PLUGINSYSTEM</tt> from? Observe the two lines in <tt>IPluginSys.h</tt>:
<cpp>#define SMINTERFACE_PLUGINSYSTEM_NAME "IPluginManager"
#define SMINTERFACE_PLUGINSYSTEM_VERSION 1</cpp>

The <tt>SM_GET_IFACE</tt> macro uses the text in between the <tt>SMINTERFACE_</tt> and the <tt>_NAME</tt> characters. It also uses the version for compatibility checking. If it can't find the interface, it automatically prints to the error buffer and returns false.

===Default Interfaces===
There are interfaces which are grabbed by the Extension SDK by default. You do not need to query for them on load, or even check if they are valid or not. They are:
*<tt>IShareSys</tt> - Exposed as <tt>sharesys</tt>, found in <tt>IShareSys.h</tt>
*<tt>HANDLESYSTEM</tt> - Exposed as <tt>handlesys</tt>, found in <tt>IHandleSys.h</tt>
*<tt>SOURCEMOD</tt> - Exposed as <tt>g_pSM</tt>, found in <tt>ISourceMod.h</tt>
*<tt>FORWARDMANAGER</tt> - Exposed as <tt>forwards</tt>, found in <tt>IForwardSys.h</tt>

===Available Interfaces===
*<tt>SMEXT_ENABLE_FORWARDSYS</tt>: <tt>forwards</tt>
*<tt>SMEXT_ENABLE_HANDLESYS</tt>: <tt>handlesys</tt>
*<tt>SMEXT_ENABLE_PLAYERHELPERS</tt>: <tt>playerhelpers</tt>
*<tt>SMEXT_ENABLE_DBMANAGER</tt>: <tt>dbi</tt>
*<tt>SMEXT_ENABLE_GAMECONF</tt>: <tt>gameconfs</tt>
*<tt>SMEXT_ENABLE_MEMUTILS</tt>: <tt>memutils</tt>
*<tt>SMEXT_ENABLE_GAMEHELPERS</tt>: <tt>gamehelpers</tt>
*<tt>SMEXT_ENABLE_TIMERSYS</tt>: <tt>timersys</tt>
*<tt>SMEXT_ENABLE_THREADER</tt>: <tt>threader</tt>

==External Interfaces==
The situation changes if your extension requires ''another extension'', since extensions may load in a completely random order. The first step is to mark the other extension as a dependency. Let's say you want to use the <tt>IThreader.h</tt> interfaces from <tt>threader.ext.dll</tt>. First, we declare it as such:

<cpp>bool Sample::SDK_OnLoad(char *error, size_t err_max, bool late)
{
sharesys->AddDependency(myself, "thread.ext", true, true);
return true;
}</cpp>

The two boolean parameters to <tt>AddDependency</tt> mean, respectively: "try to automatically load this extension" and "this extension cannot work without the dependency."

Second, we query for the interface in <tt>SDK_OnAllLoaded</tt>. Since we don't know when <tt>thread.ext</tt> will actually be loaded, we have to wait until everything is definitely loaded.
<cpp>IThreader *g_pThreader = NULL;
/* ... */
void Sample::SDK_OnAllLoaded()
{
SM_GET_LATE_IFACE(THREADER, g_pThreader);
}</cpp>

Third, we need to find a way to fail if this interface was never found. The way to do this is by uncommenting <tt>QueryRunning</tt> from <tt>extension.h</tt> and implementing it:
<cpp>bool Sample::QueryRunning(char *error, size_t err_max)
{
SM_CHECK_IFACE(THREADER, g_pThreader);
return true;
}</cpp>

When SourceMod queries your extension, the macro above will either validate the pointer or return false. If it returns false, SourceMod marks your extension as failed.

==Caveats==
===NULL Interfaces===
There are a few ways that external interfaces can make your code complicated. The first is simple but a common oversight. Don't assume interfaces will be okay. For example, say we want to create a thread once we get the <tt>IThreader</tt> interface. Our code should something like this:

<cpp>void Sample::SDK_OnAllLoaded()
{
SM_GET_IFACE(THREADER, g_pThreader);

if (QueryRunning(NULL, 0))
{
g_pThreader->MakeThread(/* stuff */);
}
}</cpp>

Note that we ''query ourself'' in order to find if it's safe to continue executing code. We could also have simply checked if <tt>g_pThreader</tt> is <tt>NULL</tt>, but self-querying has a bonus: if your extension continues to do things like hook events or add listeners, you will be preventing your extension from entirely initializing itself while one interface is bad. Always make sure you have sanity checks like this where needed.

===Dynamic Unloading===
The second major caveat is that extensions can be dynamically unloaded. If you specified yourself as having a dependency and that each dependency is required, you will have no problem. Your extension will be unloaded before the interface is removed, and you can clean up memory/hooks in your <tt>SDK_OnUnload()</tt> code. There are two situations where this is a different story.

====Optional Interfaces====
The first situation is if you are not requiring an extension that contains an interface. Now, when the extension unloads, your extension will not be unloaded first. This creates a small problem, as you must clean up without being unloaded. There are two functions you can implement in your extension class to resolve this, both documented in <tt>IExtensionSys.h</tt>:
*<tt>QueryInterfaceDrop</tt> - Allows you to request unloading when a specific interface is unloaded. This is the default behavior for all interfaces. If you want to block this functionality, continue reading.
*<tt>NotifyInterfaceDrop</tt> - This is called when an interface is dropped. If your plugin will not be unloaded, you can use this to clean up any resources on a specific interface being removed.

====Circular Dependencies====
The second situation is a bit more complicated. It is possible for two extensions to have circular dependencies. For example:
*Extension "A" requires extension "B."
*Extension "B" requires extension "A."

If either extension is unloaded, the opposite extension is unloaded normally. The first extension then receives the interface drop callbacks. In this situation, it is essential that the <tt>NotifyInterfaceDrop</tt> function be implemented and used with the circular interface. Otherwise, you risk crashing when your extension unloads (or at the very least, leaking memory). Since the actual drop order is undefined, it means both extensions must implement this function to be safe.

=Automatic Loading=
There are two types of automatic loading: Dynamic and Global. Dynamic loading means your extension is only loaded when a plugin requires it. Global loading means your extension loads no matter what.

==Dynamic Autoloading==
Dynamic loading requires that you create an include file for plugins. Plugins that include your file will automatically load your extension. This requires implementing the <tt>Extension</tt> structure found in <tt>core.inc</tt>. You must expose the structure as <tt>public</tt>, and the name must start with "<tt>__ext_</tt>".

<pawn>/**
* Do not edit below this line!
*/
public Extension:__ext_geoip =
{
name = "GeoIP",
file = "geoip.ext",
#if defined AUTOLOAD_EXTENSIONS
autoload = 1,
#else
autoload = 0,
#endif
#if defined REQUIRE_EXTENSIONS
required = 1,
#else
required = 0,
#endif
};
</pawn>

Explanations:
*name: The name of your module as written in <tt>SMEXT_CONF_NAME</tt>.
*file: The platform-inspecific portion of your extension's file name.
*autoload: Specifies that your module should always dynamically autoload by default. You can tweak this to either never autoload or always autoload (without letting the user toggle).
*required: Specifies whether or not this extension is '''required''' by your plugin. If for some reason your extension fails to load (or is not found), the plugin will also fail to load. This is changeable if you wish to override the default behavior.

You can copy and paste this example, but remember to modify the following portions:
*__ext_geoip: Change the "geoip" portion to your own unique variable name.
*"GeoIP: Change the GeoIP portion to your extension's name. This should match the name you chose as <tt>SMEXT_CONF_NAME</tt>.
*"geoip.ext": Change this to your extension's file name, without the .dll/.so portion.

==Global Autoloading==
To have your extension always autoload, you must create a ''.autoload'' file in the <tt>extensions</tt> folder. For example, to have the <tt>threader.ext.dll</tt> or <tt>threader.ext.so</tt> extensions autoload, you'd create the following file in <tt>extensions</tt>: <tt>threader.autoload</tt>.

A few notes:
*This only works for extensions using the .ext.<platform> convention. SourceMod cuts off the ".autoload" portion of the file, then adds the appropriate extension just as if 'sm exts load' was used.
*The file does not need to contain anything, it simply needs to exist.

=Conventions=

==Designing API/Natives==
*Start interface names with the capital letter 'I'.
*Use a consistent naming convention. SourceMod uses [http://msdn2.microsoft.com/en-us/library/ms229002.aspx Microsoft/Pascal] naming. Avoid Java/Camel casing for both API and natives.
*When exposing interfaces, make sure your exposure defines start with <tt>SMINTERFACE_</tt> and end with <tt>_NAME</tt> and <tt>_VERSION</tt>

==External Naming==
*Logtags (<tt>SMEXT_CONF_LOGTAG</tt>) should be short names (under 10 characters or so) in all capital letters.
*Your extension file name should never have <tt>_i486</tt> or other unnecessary platform-specific notations in its name.
*Your extension file name should always end in <tt>.ext.so</tt> or <tt>.ext.dll</tt> depending on the platform. The <tt>.ext.</tt> is SourceMod convention.

=Setting up Visual Studio=

{{qnotice|It is recommended that you make a copy of the sample_ext project and modify that rather than create your own project, as it will set up most of this for you}} 

== Sample Project ==

Instead of manually creating a project, you can make a copy of the sample_ext project and modify it.

The sample_ext project assumes that it is located in a subdirectory inside the SourceMod public directory. To change this, modify all references to ..\.. to $(SOURCEMOD15)\public and specify the SOURCEMOD15 variable as mentioned in the Optional Environment variables.

The sample_ext projectuses the following environment variables to locate the various source code parts. To set environment variables:

'''Windows XP''': Start -> Settings -> Control Panel -> System -> Advanced -> Environment Variables

'''Windows Vista/7''': Start -> Control Panel -> System -> Advanced system properties -> Advanced -> Environment Variables

=== Environment Variables ===

The environment variables used are:

* '''MMSOURCE17''': Path to MetaMod: Source source code for version 1.7 or newer. Used to compile SourceMod itself.
* '''MMSOURCE18''': Path to MetaMod: Source source code for version 1.8 or newer. Used in SourceMod 1.4 projects.
* '''MMSOURCE19''': Path to MetaMod: Source source code for version 1.9 or newer. Used in SourceMod 1.5 projects.
* '''HL2SDK''': Path to the Episode 1 SDK
* '''HL2SDK-SWARM''': Path to the Alien Swarm SDK
* '''HL2SDK-DARKM''': Path to the Dark Messiah SDK
* '''HL2SDKCSGO''': Path to the Counter-Strike: Global Offensive SDK
* '''HL2SDKCSS''': Path to the Counter-Strike: Source SDK
* '''HL2SDKL4D''': Path to the Left 4 Dead SDK
* '''HL2SDKL4D2''': Path to the Left 4 Dead 2 SDK
* '''HL2SDKOB''': Path to the Orange Box SDK (not Source 2009)
* '''HL2SDKOBVALVE''': Path to the Orange Box Valve / Source 2009 SDK (Half-Life 2: Deathmatch, Day of Defeat: Source, Team Fortress 2)

Optional environment variables:

* '''SOURCEMOD15'': Optional path to SourceMod 1.5 or newer source code

==Manually configuring a project==

===Paths===
'''Visual Studio 2003''': Tools -> Options -> Projects, VC++ Directories

'''Visual Studio 2005''': Tools -> Options -> Projects and Solutions -> VC++ Directories

====Include Paths====
*SourceMod only:
**sdk\public\extensions
**sdk\public\sourcepawn
**sdk\public
*SourceMM (Note that sourcemm might be 'trunk' for you):
**sourcemm\core
**sourcemm\core\sourcehook
*HL2SDK:
**game\shared
**public\vstdlib
**public\tier1
**public\tier0
**public\engine
**public
**dlls

====Link Paths====
*HL2SDK:
**lib\public for version 2005
**lib-vc7\public for version 2003

===Compiler Options===
Note: These options are set by default in the sample Extension SDK. 
Note: These options should be set for every build (Release/Debug/others).

For VS 2005, goto Project->Properties.

*General
**<tt>Character Set</tt>: '''Use Multi-Byte Character Set'''
*C/C++
**General
***<tt>Detect 64-bit Portability Issues</tt>: '''No'''
**Preprocessor
***<tt>Preprocessor Defines</tt>: Add <tt>_CRT_SECURE_NO_DEPRECATE</tt>, <tt>_CRT_NONSTDC_NO_DEPRECATE</tt>, <tt>SOURCEMOD_BUILD</tt> and <tt>WIN32</tt>
**Code Generation
***<tt>Runtime Library</tt>: Multi-threaded or /MT (for Release), Multi-threaded Debug or /MTd (for Debug)
*Linker
**General
***<tt>Output File</tt>: Change <tt>$(ProjectName)</tt> to <tt>$(ProjectName).ext</tt>, or use your own custom string.
**Input
***<tt>Additional Dependencies</tt>: <tt>tier0.lib tier1.lib vstdlib.lib</tt> (for SourceMM attached extensions only)

[[Category:SourceMod]]
[[Category:SourceMod Development]]

Writing Extensions

2018-01-01T21:31:48Z

Hmmmmm: Added hl2sdk github link

SourceMod's Extension System is a powerful way to greatly enhance the flexibility of your SourceMod plugins. You can take full advantage of SourceMod's Core, using the interfaces it provides, to create C++ plugins, plugin events, plugin native functions, and shared interfaces. Extensions can also hook into Metamod:Source.

This article goes into the details of creating a SourceMod Extension. Knowledge of C++ is required.

=SDK Structure=
First, download the [[SourceMod SDK]] from the [https://github.com/alliedmodders/sourcemod/releases SourceMod github], and one of the SDKs from the [https://github.com/alliedmodders/hl2sdk hl2sdk github]. The directory structure should contain these folders:
<code>
* hl2sdk-something - One of the HL2 SDKs
* sourcemod-version - The sourcemod package
** extensions - Sourcemod Extensions code
*** curl - Source code to the cURL extension
*** geoip - Source code to the GeoIP extension
*** mysql - Source code to the MySQL extension
** plugins - Source code to all of SourceMod's plugins
*** include - The include files which document plugin API
** public - Interface files for SourceMod's Core Interfaces
*** extensions - Interfaces that are provided by extensions
*** '''sample_ext''' - The Sample Extension SDK
**** extension.cpp - Sample C++ plugin
**** extension.h - Sample C++ header file
**** Makefile - Sample C++ plugin compiler
**** smsdk_config.h - Sample C++ plugin settings
** sourcepawn - The include/interface files for SourcePawn
*** compiler - The SourcePawn Compiler
</code>

=Starting an Extension=
For simplicity, this article will assume you are using the SDK base files. Navigate to <code>extensions/public/sample_ext</code>, and ensure that you can compile your code. If using the command line, <code>make</code> should do this, if using Visual Studio, see [[#Setting up Visual Studio|Setting up Visual Studio]].

The first step of creating your extension is to configure it. Open the <tt>smsdk_config.h</tt> file and edit each of the following defines. Use the information below to guide you.
<code>
*SMEXT_CONF_NAME - The general name for your Extension (should be short).
*SMEXT_CONF_DESCRIPTION - A short description of what your extension does.
*SMEXT_CONF_VERSION - A version number string. By convention, SourceMod uses the four set build number notation, so build 1.2.3.4 means:
**1 is the "Major" release version.
**2 is the "Minor" release version.
**3 is the "Maintenance" or "Revision" version.
**4 is the "Build," usually an internal source control number.
*SMEXT_CONF_AUTHOR - Your name (or whoever/whatever authored the plugin).
*SMEXT_CONF_URL - The URL/homepage of this extension.
*SMEXT_CONF_LOGTAG - The logtag your extension will use for SourceMod logging. By convention, try to keep this under ten characters or so, and to make it all caps.
*SMEXT_CONF_LICENSE - Right now, the SourceMod Dev Team mandates that 3rd party extensions must be under an Open Source license. Putting a license abbreviation or very short message here is appropriate. For more information, see [https://www.sourcemod.net/license.php the SourceMod license].
*SMEXT_CONF_DATESTRING - You do not need to modify this.
</code>
If your plugin requires using SourceHook or Metamod:Source, uncomment this line:
<code>#define SMEXT_CONF_METAMOD</code>

Next, you should change the name of your extension. By convention, your extension's class name should start with a capital letter.
* First, open <code>extension.h</code> and change "Sample" in this line:
<cpp>class Sample : public SDKExtension</cpp>
* Next, open <code>extension.cpp</code> change these two lines:
<cpp>Sample g_Sample;
SMEXT_LINK(&g_Sample);</cpp>

==Visual Studio Users==
Make sure you change the name of your <tt>.dll</tt> file. The naming convention for SourceMod extensions is <tt>name.ext.dll</tt>, where <tt>name</tt> is a short name for your extension. You are free to change this, but it is highly recommended that you keep the <tt>.ext.dll</tt> intact.

You can do this by going to <tt>Project</tt> -> <tt>Properties</tt> -> <tt>Configuration Properties</tt> -> <tt>Linker</tt> -> <tt>General</tt>. Set the <tt>Output File</tt> option appropriately.

==Linux Users==
Simply edit the <tt>Makefile</tt> and change the <tt>BINARY</tt> line near the top. Make sure you do not add any trailing spaces at the end of the name, or the build won't come out right.

You should now be able to compile a blank extension!

=Creating Native Functions=
''Main article: [[Natives (SourceMod Development)]]''

Most of the time, an extension exists to add "native functions" to the plugin system. Native functions are simply the functions that plugins can use in SourceMod. They are coded in C++ and have a short prototype declaration in an include file.

==Prototyping==
The first step to creating a native is to <tt>spec it</tt>, or <tt>prototype</tt> it. This is a simple but often time consuming process, but if you get in the habit of it, your documentation will be much better. Let's first create a very simply native. Here is a prototype for it, which we will place in <tt>sample.inc</tt>:
<pawn>/**
* Returns the square of a number.
*
* @param num Number to square.
* @return The square of num.
*/
native SquareNumber(num);</pawn>

The <tt>native</tt> keyword tells the compiler that this function exists in an outside source. The comment style is similar to [http://www.stack.nl/~dimitri/doxygen/ doxygen] or [http://java.sun.com/j2se/javadoc/ Javadoc], and is preferred by the SourceMod Development Team.

==Implementing==
Now that our function is documented, it's time to create it! Each native function is bound to a C++ function. The prototype for this function looks like:
<cpp>cell_t Function(IPluginContext *pContext, const cell_t *params);</cpp>

A quick explanation of these types:
*<tt>cell_t</tt> - This is a 32bit signed integer, the generic data type for Pawn.
*<tt>IPluginContext</tt> - This interface provides Virtual Machine functions for retrieving or modifying memory in the plugin.
*<tt>params</tt> - This is the "stack" of parameters that the plugin passed. It is an array from [0..N] where 0 contains N. This means <tt>params[0]</tt> contains the number of arguments passed to the native.
**For example, if one parameter was passed, and the parameter is 25:
***<tt>params[0]</tt> == 1
***<tt>params[1]</tt> == 25
**Even though it tells you how many parameters are passed, you do not need to verify this number. The compiler will always pass the correct number of parameters in. The only time you need to verify it is for backwards compatibility or variable parameter lists, which will be discussed later.

Now, let's write our native function:
<cpp>cell_t SquareNumber(IPluginContext *pContext, const cell_t *params)
{
cell_t number = params[1];
return number * number;
}</cpp>

==Binding==
Now, the final step is to bind our native. Natives are bound in ''native lists''. Each list must be terminated by a <tt>NULL</tt> bind. Example:
<cpp>const sp_nativeinfo_t MyNatives[] =
{
{"SquareNumber", SquareNumber},
{NULL, NULL},
};</cpp>

The first column/member is a string containing the name you've assigned to the native. The second column/member is the C++ function you're binding to. Here, both contain the same name, but it is certainly possible to bind a function to any valid Pawn function name, and likewise, you can bind one function to more than one name.

Lastly, you must tell Core about your native list. There are two places that are good to do this. Whichever you choose, you must uncomment the function in <tt>extension.h</tt> and implement it in <tt>extension.cpp</tt>.
*<tt>SDK_OnLoad</tt> - This is called when your extension is first loaded. If you do not require any outside interfaces, it is safe to add natives here.
*<tt>SDK_OnAllLoaded</tt> - This is called when all extensions have been loaded. This is generally a better place to add natives.

Let's say we choose <tt>SDK_OnAllLoaded</tt>, we'd then have code like this:
<cpp>void Sample::SDK_OnAllLoaded()
{
sharesys->AddNatives(myself, MyNatives);
}</cpp>
''Note: <tt>myself</tt> is a global variable declared in the SDK. It is a pointer that identifies your extension.''

For more information on writing natives, see [[Natives (SourceMod Development)]].

=Creating Events/Forwards=
Events are an integral part to SourceMod. An Event is formally called a ''Forward''. Forwards are functions inside a plugin which are not called by the plugin itself, but are triggered from an external source. For example, <tt>OnClientConnect</tt> is a forward which is triggered when a player connects to a server.

There are two major types of forwards:
*'''Managed''': This forward is global and has a name. To use this forward, the function must be declared as <tt>public</tt> inside the user's script. Any plugin having this public function will receive the event.
*'''Unmanaged''': This forward is private in nature. For example, the <tt>HookUserMessage</tt> native lets users specify a function to be called when a specific user message is sent. This is done with an unmanaged forward, and adding functions to this forward is not automatic. In general, function calls for unmanaged forwards are not public, although they can be.

''Note: To enable the Forward interface, you must uncomment the definition <tt>SMEXT_ENABLE_FORWARDSYS</tt> in smsdk_config.h.''
==Managed Forwards==
Let's say we want to create a forward that will be called when a player uses say chat. For simplicity, let's assume you already have a function that tells you when a player says say chat. We will just be creating the forward for it.

As we did before, first let's prototype our global forward. In our include file, we add this:
<pawn>/**
* @brief Called whenever a client says something in chat.
*
* @param client Index of the client.
* @param text String containing the say text.
* @return Pl_Handled to block text from printing, Pl_Continue otherwise.
*/
forward ResultType:OnPlayerSayChat(client, const String:text[]);</pawn>

The <tt>forward</tt> keyword tells the compiler that any function having this name must be declared exactly the same. In a plugin, this would

The next step is to declare your forward somewhere at the top of your <tt>extension.cpp</tt> file. This will look like:
<cpp>IForward *g_pSayChat = NULL</cpp>

Next, re-using our code from above, let's create this forward in <tt>SDK_OnAllLoaded</tt>:
<cpp>void Sample::SDK_OnAllLoaded()
{
sharesys->AddNatives(myself, MyNatives);
g_pSayChat = forwards->CreateForward("OnPlayerSayChat", ET_Event, 2, NULL, Param_Cell, Param_String);
}</cpp>

Explanation of parameters:
*<tt>"OnPlayerSayChat"</tt> - The name of our forward.
*<tt>ET_Event</tt> - Since forwards can execute multiple functions in multiple scripts, this is one of the ways of specifying what to do with the return value of each function. <tt>ET_Event</tt> means "return the highest value, do not allow stops." A stop refers to <tt>Pl_Stop</tt>, which lets a plugin block the rest of the event chain.
*<tt>2</tt> - This is the number of parameters our forward will have.
*<tt>NULL</tt> - Not used in our example. This lets you pass parameters by array rather than variable arguments.
*<tt>Param_Cell</tt> - The first parameter is a cell (integer).
*<tt>Param_String</tt> - The second parameter is a string.

Now, we write a quick function in our module to call this forward:
<cpp>/** Fires the say chat event in plugins. Returns true to allow the text, false to block. */
bool FireChatEvent(int client, const char *text)
{
if (!g_pSayChat)
{
return true;
}

cell_t result = 0;
g_pSayChat->PushCell(client);
g_pSayChat->PushString(text);
g_pSayChat->Execute(&result);

if (result == Pl_Handled)
{
return false;
}

return true;
}</cpp>

As you can see, this was pretty simple. Each parameter is "pushed" one at a time, in ascending order. First we push the client index as a cell, then the text as a string. Once done, we execute, and the value will be returned by reference.

Lastly, there is a caveat. Unlike natives, SourceMod does not automatically clean up forwards for us when are done. We have to make sure we destroy them. Uncomment <tt>SDK_OnUnload</tt> from <tt>extension.h</tt> and implement it like so:
<cpp>void Sample::SDK_OnUnload()
{
forwards->ReleaseForward(g_pSayChat);
}</cpp>

==Unmanaged Forwards==
Now things get a bit more complicated. However, unmanaged forwards are essentially the same -- they just give you more flexibility. Let's consider the managed example with a new twist. We want to let users add and remove hooks from their plugins, rather than having one global forward. The standard way to do this is with ''function IDs''.

Example prototype:
<pawn>funcenum SayChatHook
{
forward(client, const String:text[]);
}

native AddSayChatHook(SayChatHook:hook);
native RemoveSayChatHook(SayChatHook:hook);</pawn>

The <tt>funcenum</tt> syntax lets you define all the valid prototypes for your hook. In this example, the only valid method is a function declared like this (only MyHook can be changed):
<pawn>MyHook(client, const String:text[])</pawn>

How do we make such a beast? The first step is setting up our forward.
<cpp>IChangeableForward *g_pSayChat = NULL;
/* ... */
void Sample::SDK_OnAllLoaded()
{
g_pSayChat = forwards->CreateForwardEx(NULL, ET_Hook, 2, NULL, Param_Cell, Param_String);
}</cpp>

Notice two big differences. We now use <tt>IChangeableForward</tt> instead of <tt>IForward</tt>, and we use <tt>CreateForwardEx</tt> instead. The initial first parameter specifies a name for our forward - we're going to ignore this.

Now, we need to create our natives. These will be fairly simple:
<cpp>cell_t AddSayChatHook(IPluginContext *pContext, const cell_t *params)
{
g_pSayChat->AddFunction(pContext, static_cast<funcid_t>(params[1]));
return 1;
}

cell_t RemoveSayChatHook(IPluginContext *pContext, const cell_t *params)
{
IPluginFunction *pFunction = pContext->GetFunctionById(static_cast<funcid_t>(params[1]));
g_pSayChat->RemoveFunction(pFunction);
return 1;
}</cpp>
''Note: These natives must be added -- that step is removed here and explained earlier.''

You do not need to worry about a plugin unloading - Core will automatically remove the functions for you. Since an <tt>IChangeableForward</tt> is also an <tt>IForward</tt>, the <tt>FireChatEvent</tt> function from earlier does not need to change. We're done!

==Creating Interfaces==
Do you want your extension to share an interface? If so, first you should create an ''interface file''. This file should contain everything your interface needs - this way other authors can easily reference it. Your interface must inherit the <tt>SMInterface</tt> class. It must also declare two global macros that uniquely identify your interface. It must also implement two functions: <tt>GetInterfaceName</tt> and <tt>GetInterfaceVersion</tt>.

The two defines must start with <tt>SMINTERFACE_</tt> and end with <tt>_NAME</tt> and <tt>_VERSION</tt> respectively. The first must be a string and the second must be an unsigned integer. This integer represents your interface's version number. While you are free to use it however you please, by default it should be linearly increased. If you make breaking changes or change the versioning scheme, you must overload the <tt>IsVersionCompat</tt> function in <tt>SMInterface</tt>.

Example:
<cpp>#ifndef _INCLUDE_MYINTERFACE_FILE_H_
#define _INCLUDE_MYINTERFACE_FILE_H_

#include <IShareSys.h>

#define SMINTERFACE_MYINTERFACE_NAME "IMyInterface"
#define SMINTERFACE_MYINTERFACE_VERSION 1

class IMyInterface : public SourceMod::SMInterface
{
public:
virtual const char *GetInterfaceName()
{
return SMINTERFACE_MYINTERFACE_NAME;
}
virtual unsigned int GetInterfaceVersion()
{
return SMINTERFACE_MYINTERFACE_VERSION;
}
public:
/**
* @brief This function does nothing.
*/
virtual void DoNothingAtAll() =0;
};

#endif //_INCLUDE_MYINTERFACE_FILE_H_</cpp>

Notice, of course, that our interface is ''pure virtual''. This means it must be implemented in the extension. Assuming you know C++, this should be fairly straight forward, so let's skip right to how to add this interface to the SourceMod shared system:
<cpp>bool Sample::SDK_OnLoad(char *error, size_t err_max, bool late)
{
sharesys->AddInterface(myself, &g_MyInterface);
return true;
}</cpp>
''Note: We do this in <tt>SDK_OnLoad()</tT> instead of <tt>SDK_OnAllLoaded()</tt>. Otherwise, an extension might try to search for your interface during <tt>SDK_OnAllLoaded()</tt>, and it might fail depending on the load order.''

That simple? Yup! Now other extensions can use your interface.

=Using Interfaces/Other Extensions=
There are a variety of interfaces that are available, but not loaded by default in the Extension SDK. These interfaces can be retrieved and used in your extension.

==Core Interfaces==
If they are provided by Core, getting them is very simple. Many interfaces can simply be uncommented in <tt>smsdk_config.h</tt> and they will become usable. See the "Available Interfaces" list below for the exposure list.

Otherwise, most of the <tt>.h</tt> interface files in the root of the <tt>public</tt> folder in the SDK are Core interfaces. For example, code to use the IPluginManager interface might look like this:
<cpp>#include <IPluginSys.h>

IPluginManager *g_pPlugins = NULL;

bool Sample::SDK_OnLoad(char *error, size_t err_max, bool late)
{
SM_GET_IFACE(PLUGINSYSTEM, g_pPlugins);
return true;
}</cpp>

Where did we get <tt>PLUGINSYSTEM</tt> from? Observe the two lines in <tt>IPluginSys.h</tt>:
<cpp>#define SMINTERFACE_PLUGINSYSTEM_NAME "IPluginManager"
#define SMINTERFACE_PLUGINSYSTEM_VERSION 1</cpp>

The <tt>SM_GET_IFACE</tt> macro uses the text in between the <tt>SMINTERFACE_</tt> and the <tt>_NAME</tt> characters. It also uses the version for compatibility checking. If it can't find the interface, it automatically prints to the error buffer and returns false.

===Default Interfaces===
There are interfaces which are grabbed by the Extension SDK by default. You do not need to query for them on load, or even check if they are valid or not. They are:
*<tt>IShareSys</tt> - Exposed as <tt>sharesys</tt>, found in <tt>IShareSys.h</tt>
*<tt>HANDLESYSTEM</tt> - Exposed as <tt>handlesys</tt>, found in <tt>IHandleSys.h</tt>
*<tt>SOURCEMOD</tt> - Exposed as <tt>g_pSM</tt>, found in <tt>ISourceMod.h</tt>
*<tt>FORWARDMANAGER</tt> - Exposed as <tt>forwards</tt>, found in <tt>IForwardSys.h</tt>

===Available Interfaces===
*<tt>SMEXT_ENABLE_FORWARDSYS</tt>: <tt>forwards</tt>
*<tt>SMEXT_ENABLE_HANDLESYS</tt>: <tt>handlesys</tt>
*<tt>SMEXT_ENABLE_PLAYERHELPERS</tt>: <tt>playerhelpers</tt>
*<tt>SMEXT_ENABLE_DBMANAGER</tt>: <tt>dbi</tt>
*<tt>SMEXT_ENABLE_GAMECONF</tt>: <tt>gameconfs</tt>
*<tt>SMEXT_ENABLE_MEMUTILS</tt>: <tt>memutils</tt>
*<tt>SMEXT_ENABLE_GAMEHELPERS</tt>: <tt>gamehelpers</tt>
*<tt>SMEXT_ENABLE_TIMERSYS</tt>: <tt>timersys</tt>
*<tt>SMEXT_ENABLE_THREADER</tt>: <tt>threader</tt>

==External Interfaces==
The situation changes if your extension requires ''another extension'', since extensions may load in a completely random order. The first step is to mark the other extension as a dependency. Let's say you want to use the <tt>IThreader.h</tt> interfaces from <tt>threader.ext.dll</tt>. First, we declare it as such:

<cpp>bool Sample::SDK_OnLoad(char *error, size_t err_max, bool late)
{
sharesys->AddDependency(myself, "thread.ext", true, true);
return true;
}</cpp>

The two boolean parameters to <tt>AddDependency</tt> mean, respectively: "try to automatically load this extension" and "this extension cannot work without the dependency."

Second, we query for the interface in <tt>SDK_OnAllLoaded</tt>. Since we don't know when <tt>thread.ext</tt> will actually be loaded, we have to wait until everything is definitely loaded.
<cpp>IThreader *g_pThreader = NULL;
/* ... */
void Sample::SDK_OnAllLoaded()
{
SM_GET_LATE_IFACE(THREADER, g_pThreader);
}</cpp>

Third, we need to find a way to fail if this interface was never found. The way to do this is by uncommenting <tt>QueryRunning</tt> from <tt>extension.h</tt> and implementing it:
<cpp>bool Sample::QueryRunning(char *error, size_t err_max)
{
SM_CHECK_IFACE(THREADER, g_pThreader);
return true;
}</cpp>

When SourceMod queries your extension, the macro above will either validate the pointer or return false. If it returns false, SourceMod marks your extension as failed.

==Caveats==
===NULL Interfaces===
There are a few ways that external interfaces can make your code complicated. The first is simple but a common oversight. Don't assume interfaces will be okay. For example, say we want to create a thread once we get the <tt>IThreader</tt> interface. Our code should something like this:

<cpp>void Sample::SDK_OnAllLoaded()
{
SM_GET_IFACE(THREADER, g_pThreader);

if (QueryRunning(NULL, 0))
{
g_pThreader->MakeThread(/* stuff */);
}
}</cpp>

Note that we ''query ourself'' in order to find if it's safe to continue executing code. We could also have simply checked if <tt>g_pThreader</tt> is <tt>NULL</tt>, but self-querying has a bonus: if your extension continues to do things like hook events or add listeners, you will be preventing your extension from entirely initializing itself while one interface is bad. Always make sure you have sanity checks like this where needed.

===Dynamic Unloading===
The second major caveat is that extensions can be dynamically unloaded. If you specified yourself as having a dependency and that each dependency is required, you will have no problem. Your extension will be unloaded before the interface is removed, and you can clean up memory/hooks in your <tt>SDK_OnUnload()</tt> code. There are two situations where this is a different story.

====Optional Interfaces====
The first situation is if you are not requiring an extension that contains an interface. Now, when the extension unloads, your extension will not be unloaded first. This creates a small problem, as you must clean up without being unloaded. There are two functions you can implement in your extension class to resolve this, both documented in <tt>IExtensionSys.h</tt>:
*<tt>QueryInterfaceDrop</tt> - Allows you to request unloading when a specific interface is unloaded. This is the default behavior for all interfaces. If you want to block this functionality, continue reading.
*<tt>NotifyInterfaceDrop</tt> - This is called when an interface is dropped. If your plugin will not be unloaded, you can use this to clean up any resources on a specific interface being removed.

====Circular Dependencies====
The second situation is a bit more complicated. It is possible for two extensions to have circular dependencies. For example:
*Extension "A" requires extension "B."
*Extension "B" requires extension "A."

If either extension is unloaded, the opposite extension is unloaded normally. The first extension then receives the interface drop callbacks. In this situation, it is essential that the <tt>NotifyInterfaceDrop</tt> function be implemented and used with the circular interface. Otherwise, you risk crashing when your extension unloads (or at the very least, leaking memory). Since the actual drop order is undefined, it means both extensions must implement this function to be safe.

=Automatic Loading=
There are two types of automatic loading: Dynamic and Global. Dynamic loading means your extension is only loaded when a plugin requires it. Global loading means your extension loads no matter what.

==Dynamic Autoloading==
Dynamic loading requires that you create an include file for plugins. Plugins that include your file will automatically load your extension. This requires implementing the <tt>Extension</tt> structure found in <tt>core.inc</tt>. You must expose the structure as <tt>public</tt>, and the name must start with "<tt>__ext_</tt>".

<pawn>/**
* Do not edit below this line!
*/
public Extension:__ext_geoip =
{
name = "GeoIP",
file = "geoip.ext",
#if defined AUTOLOAD_EXTENSIONS
autoload = 1,
#else
autoload = 0,
#endif
#if defined REQUIRE_EXTENSIONS
required = 1,
#else
required = 0,
#endif
};
</pawn>

Explanations:
*name: The name of your module as written in <tt>SMEXT_CONF_NAME</tt>.
*file: The platform-inspecific portion of your extension's file name.
*autoload: Specifies that your module should always dynamically autoload by default. You can tweak this to either never autoload or always autoload (without letting the user toggle).
*required: Specifies whether or not this extension is '''required''' by your plugin. If for some reason your extension fails to load (or is not found), the plugin will also fail to load. This is changeable if you wish to override the default behavior.

You can copy and paste this example, but remember to modify the following portions:
*__ext_geoip: Change the "geoip" portion to your own unique variable name.
*"GeoIP: Change the GeoIP portion to your extension's name. This should match the name you chose as <tt>SMEXT_CONF_NAME</tt>.
*"geoip.ext": Change this to your extension's file name, without the .dll/.so portion.

==Global Autoloading==
To have your extension always autoload, you must create a ''.autoload'' file in the <tt>extensions</tt> folder. For example, to have the <tt>threader.ext.dll</tt> or <tt>threader.ext.so</tt> extensions autoload, you'd create the following file in <tt>extensions</tt>: <tt>threader.autoload</tt>.

A few notes:
*This only works for extensions using the .ext.<platform> convention. SourceMod cuts off the ".autoload" portion of the file, then adds the appropriate extension just as if 'sm exts load' was used.
*The file does not need to contain anything, it simply needs to exist.

=Conventions=

==Designing API/Natives==
*Start interface names with the capital letter 'I'.
*Use a consistent naming convention. SourceMod uses [http://msdn2.microsoft.com/en-us/library/ms229002.aspx Microsoft/Pascal] naming. Avoid Java/Camel casing for both API and natives.
*When exposing interfaces, make sure your exposure defines start with <tt>SMINTERFACE_</tt> and end with <tt>_NAME</tt> and <tt>_VERSION</tt>

==External Naming==
*Logtags (<tt>SMEXT_CONF_LOGTAG</tt>) should be short names (under 10 characters or so) in all capital letters.
*Your extension file name should never have <tt>_i486</tt> or other unnecessary platform-specific notations in its name.
*Your extension file name should always end in <tt>.ext.so</tt> or <tt>.ext.dll</tt> depending on the platform. The <tt>.ext.</tt> is SourceMod convention.

=Setting up Visual Studio=

{{qnotice|It is recommended that you make a copy of the sample_ext project and modify that rather than create your own project, as it will set up most of this for you}} 

== Sample Project ==

Instead of manually creating a project, you can make a copy of the sample_ext project and modify it.

The sample_ext project assumes that it is located in a subdirectory inside the SourceMod public directory. To change this, modify all references to ..\.. to $(SOURCEMOD15)\public and specify the SOURCEMOD15 variable as mentioned in the Optional Environment variables.

The sample_ext projectuses the following environment variables to locate the various source code parts. To set environment variables:

'''Windows XP''': Start -> Settings -> Control Panel -> System -> Advanced -> Environment Variables

'''Windows Vista/7''': Start -> Control Panel -> System -> Advanced system properties -> Advanced -> Environment Variables

=== Environment Variables ===

The environment variables used are:

* '''MMSOURCE17''': Path to MetaMod: Source source code for version 1.7 or newer. Used to compile SourceMod itself.
* '''MMSOURCE18''': Path to MetaMod: Source source code for version 1.8 or newer. Used in SourceMod 1.4 projects.
* '''MMSOURCE19''': Path to MetaMod: Source source code for version 1.9 or newer. Used in SourceMod 1.5 projects.
* '''HL2SDK''': Path to the Episode 1 SDK
* '''HL2SDK-SWARM''': Path to the Alien Swarm SDK
* '''HL2SDK-DARKM''': Path to the Dark Messiah SDK
* '''HL2SDKCSGO''': Path to the Counter-Strike: Global Offensive SDK
* '''HL2SDKCSS''': Path to the Counter-Strike: Source SDK
* '''HL2SDKL4D''': Path to the Left 4 Dead SDK
* '''HL2SDKL4D2''': Path to the Left 4 Dead 2 SDK
* '''HL2SDKOB''': Path to the Orange Box SDK (not Source 2009)
* '''HL2SDKOBVALVE''': Path to the Orange Box Valve / Source 2009 SDK (Half-Life 2: Deathmatch, Day of Defeat: Source, Team Fortress 2)

Optional environment variables:

* '''SOURCEMOD15'': Optional path to SourceMod 1.5 or newer source code

==Manually configuring a project==

===Paths===
'''Visual Studio 2003''': Tools -> Options -> Projects, VC++ Directories

'''Visual Studio 2005''': Tools -> Options -> Projects and Solutions -> VC++ Directories

====Include Paths====
*SourceMod only:
**sdk\public\extensions
**sdk\public\sourcepawn
**sdk\public
*SourceMM (Note that sourcemm might be 'trunk' for you):
**sourcemm\core
**sourcemm\core\sourcehook
*HL2SDK:
**game\shared
**public\vstdlib
**public\tier1
**public\tier0
**public\engine
**public
**dlls

====Link Paths====
*HL2SDK:
**lib\public for version 2005
**lib-vc7\public for version 2003

===Compiler Options===
Note: These options are set by default in the sample Extension SDK. 
Note: These options should be set for every build (Release/Debug/others).

For VS 2005, goto Project->Properties.

*General
**<tt>Character Set</tt>: '''Use Multi-Byte Character Set'''
*C/C++
**General
***<tt>Detect 64-bit Portability Issues</tt>: '''No'''
**Preprocessor
***<tt>Preprocessor Defines</tt>: Add <tt>_CRT_SECURE_NO_DEPRECATE</tt>, <tt>_CRT_NONSTDC_NO_DEPRECATE</tt>, <tt>SOURCEMOD_BUILD</tt> and <tt>WIN32</tt>
**Code Generation
***<tt>Runtime Library</tt>: Multi-threaded or /MT (for Release), Multi-threaded Debug or /MTd (for Debug)
*Linker
**General
***<tt>Output File</tt>: Change <tt>$(ProjectName)</tt> to <tt>$(ProjectName).ext</tt>, or use your own custom string.
**Input
***<tt>Additional Dependencies</tt>: <tt>tier0.lib tier1.lib vstdlib.lib</tt> (for SourceMM attached extensions only)

[[Category:SourceMod]]
[[Category:SourceMod Development]]