AlliedModders Wiki - User contributions [en]

Menu API (SourceMod)

2009-08-12T03:45:58Z

Applecorc: Added Semi-colons

SourceMod has an extensive API for building and displaying menus to clients. Unlike AMX Mod X, this API is highly state driven. Menus are based on callbacks which are guaranteed to be fired.

For C++, the Menu API can be found in <tt>public/IMenuManager.h</tt>. For SourcePawn, it is in <tt>plugins/include/menus.inc</tt>.

=Objects=
The SourceMod Menu System is based on an object oriented hierarchy. Understanding this hierarchy, even for scripting, is critical to using menus effectively.

==Styles==
The top level object is a ''MenuStyle'' (<tt>IMenuStyle</tt> in C++). Styles describe a unique menu system. There are two such styles built into SourceMod:
*Valve Style, also called "ESC" menus; 8 items per page, no raw/disabled text can be rendered
*Radio Style, also called "AMX" menus; 10 items per page, raw/disabled text can be rendered

Each MenuStyle has its own rules and properties. You can think of them as existing on separate "channels." For example, two different menus can exist on a player's screen as both a Valve menu and a Radio menu at the same time, and SourceMod will be able to manage both without any problems. This is because each style keeps track of its own menus separately.

==Panels==
Menu displays are drawn with a lower level interface called ''Panels'' (<tt>IMenuPanel</tt> in C++). Panels describe exactly one chunk of display text. Both selectable items and raw text can be added to a panel as long as its parent style supports the contents you're trying to draw. For example, the Valve style does not support drawing raw text or disabled items. But with a Radio-style Panel, you can display a large amount of on-screen data in your own format.

Panels are considered temporary objects. They are created, rendered, displayed, and destroyed. Although they can be saved indefinitely, it is not necessary to do so.

Valve Style drawing rules/limitations:
*Max items per page is 8.
*Disabled items cannot be drawn.
*Raw text cannot be drawn.
*Spacers do not add a space/newline, giving a "cramped" feel.
*Users must press "ESC" or be at their console to view the menu.

Radio Style drawing rules/limitations:
*Max items per page is 10.
*Titles appear white; items appear yellow, unless disabled, in which case they are white.
*The 0th item is always white. For consistency, this means navigational controls explained in the next section are always white, and simply not drawn if disabled.

==Menus==
Lastly, there are plain ''Menus'' (<tt>IBaseMenu</tt> in C++). These are helper objects designed for storing a menu based on selectable items. Unlike low-level panels, menus are containers for '''items''', and can only contain items which are selectable (i.e., do not contain raw text). They fall into two categories:
*Non-paginated: The menu can only have a certain number of items on it, and no control/navigation options will be added, except for an "Exit" button which will always be in the last position supported by the style.
**Valve Style maximum items: 8
**Radio Style maximum items: 10
*Paginated: The menu can have any number of items. When displayed, only a certain number of items will be drawn at a time. Automatic navigation controls are added so players can easily move back and forth to different "pages" of items in the menu.
**"Previous" is always drawn as the first navigation item, third from the last supported position. This will not be drawn if the menu only contains one page. If there are no previous pages, the text will not be drawn on either style; if possible, the menu will be padded so spacing is consistent.
***Valve Style position: 6
***Radio Style position: 8
**"Next" is always drawn as the second navigation item, second from the last supported position. This will not be drawn if the menu only contains one page. If there are no further pages, the text will not be drawn on either style; if possible, the menu will be padded so spacing is consistent.
***Valve Style position: 7
***Radio Style position: 9
**"Exit" is drawn if the menu has the exit button property set. It is always the last supported item position.
***Valve Style position: 8
***Radio Style position: 10

The purpose of Menus is to simplify the procedure of storing, drawing, and calculating the selection of items. Thus, menus do not allow for adding raw text, as that would considerably complicate the drawing algorithm. ''Note: The C++ API supports hooking <tt>IBaseMenu</tt> drawing procedures and adding raw text; this will be added to the scripting API soon.''

Internally, Menus are drawn via a ''RenderMenu'' algorithm. This algorithm creates a temporary panel and fills it with items from menus. This panel is then displayed to a client. The algorithm attempts to create a consistent feel across all menus, and across all styles. Thus any menu displayed via the <tt>IBaseMenu</tt> class, or <tt>Menu</tt> Handles, will look and act the same, and the Menu API is based off the Panel API.

=Callbacks=
==Overview==
Menus are a callback based system. Each callback represents an action that occurs during a ''menu display cycle''. A cycle consists of a number of notifications:
*Start notification.
**Display notification if the menu can be displayed to the client.
**Either an item select or menu cancel notification.
*End notification.

Since ''End'' signifies the end of a full display cycle, it is usually used to destroy temporary menus.

==Specification==
A detailed explanation of these events is below. For C++, an <tt>IBaseMenu</tt> pointer is always available. For SourcePawn, a <tt>Menu</tt> Handle and a <tt>MenuAction</tt> are always set in the <tt>MenuHandler</tt> callback. Unlike C++, the SourcePawn API allows certain actions to only be called if they are requested at menu creation time. This is an optimization. However, certain actions cannot be prevented from being called.

*'''Start'''. The menu has been acknowledged. This does not mean it will be displayed; however, it guarantees that "OnMenuEnd" will be called.
**<tt>OnMenuStart()</tt> in C++.
**<tt>MenuAction_Start</tt> in SourcePawn. This action is not triggered unless requested.
***<tt>param1</tt>: Ignored (always 0).
***<tt>param2</tt>: Ignored (always 0).
*'''Display'''. The menu is being displayed to a client.
**<tt>OnMenuDisplay()</tt> in C++. An <tt>IMenuPanel</tt> pointer and client index are available.
**<tt>MenuAction_Display</tt> in SourcePawn. This action is not triggered unless requested.
***<tt>param1</tt>: A client index.
***<tt>param2</tt>: A Handle to a menu panel.
*'''Select'''. An item on the menu has been selected. The item position given will be the position in the menu, rather than the key pressed (unless the menu is a raw panel).
**<tt>OnMenuSelect()</tt> in C++. A client index and item position are passed.
**<tt>MenuAction_Select</tt> in SourcePawn. This action is always triggerable, whether requested or not.
***<tt>param1</tt>: A client index.
***<tt>param2</tt>: An item position.
*'''Cancel'''. The menu's display to one client has been cancelled.
**<tt>OnMenuCancel()</tt> in C++. A reason for cancellation is provided.
**<tt>MenuAction_Cancel</tt> in SourcePawn. This action is always triggerable, whether requested or not.
***<tt>param1</tt>: A client index.
***<tt>param2</tt>: A menu cancellation reason code.
*'''End'''. The menu's display cycle has finished; this means that the "Start" action has occurred, and either "Select" or "Cancel" has occurred thereafter. This is typically where menu resources are removed/deleted.
**<tt>OnMenuEnd()</tt> in C++.
**<tt>MenuAction_End</tt> in SourcePawn. This action is always triggered, whether requested or not.
***<tt>param1</tt>: A menu end reason code.
***<tt>param2</tt>: If param1 was MenuEnd_Cancelled, this contains a menu cancellation reason code.

==Panels==
For panels, the callback rules change. Panels only receive two of the above callbacks, and it is guaranteed that only one of them will be called for a given display cycle. For C++, the <tt>IBaseMenu</tt> pointer will always be <tt>NULL</tt>. For SourcePawn, the menu Handle will always be <tt>INVALID_HANDLE</tt>.

*'''Select'''. A key has been pressed. This can be any number and should not be considered as reliably in bounds. For example, even if you only had 2 items in your panel, a client could trigger a key press of "43."
**<tt>OnMenuSelect()</tt> in C++. A client index and key number pressed are passed.
**<tt>MenuAction_Select</tt> in SourcePawn.
***<tt>param1</tt>: A client index.
***<tt>param2</tt>: Number of the key pressed.
*'''Cancel'''. The menu's display to one client has been cancelled.
**<tt>OnMenuCancel()</tt> in C++. A reason for cancellation is provided.
**<tt>MenuAction_Cancel</tt> in SourcePawn.
***<tt>param1</tt>: A client index.
***<tt>param2</tt>: A menu cancellation reason code.

=Examples=
First, let's start off with a very basic menu. We want the menu to look like this:

<pre>Do you like apples?
1. Yes
2. No</pre>

We'll draw this menu with both a basic Menu and a Panel to show the API differences.

==Basic Menu==
First, let's write our example using the Menu building API.

<pawn>public OnPluginStart()
{
RegConsoleCmd("menu_test1", Menu_Test1);
}

public MenuHandler1(Handle:menu, MenuAction:action, param1, param2)
{
/* If an option was selected, tell the client about the item. */
if (action == MenuAction_Select)
{
new String:info[32];
new bool:found = GetMenuItem(menu, param2, info, sizeof(info));
PrintToConsole(param1, "You selected item: %d (found? %d info: %s)", param2, found, info);
}
/* If the menu was cancelled, print a message to the server about it. */
else if (action == MenuAction_Cancel)
{
PrintToServer("Client %d's menu was cancelled. Reason: %d", param1, param2);
}
/* If the menu has ended, destroy it */
else if (action == MenuAction_End)
{
CloseHandle(menu);
}
}

public Action:Menu_Test1(client, args)
{
new Handle:menu = CreateMenu(MenuHandler1);
SetMenuTitle(menu, "Do you like apples?");
AddMenuItem(menu, "yes", "Yes");
AddMenuItem(menu, "no", "No");
SetMenuExitButton(menu, false);
DisplayMenu(menu, client, 20);

return Plugin_Handled;
}</pawn>

Note a few very important points from this example:
*One of either <tt>Select</tt> or <tt>Cancel</tt> will always be sent to the action handler.
*<tt>End</tt> will always be sent to the action handler.
*We destroy our Menu in the <tt>End</tt> action, because our Handle is no longer needed. If we had destroyed the Menu after <tt>DisplayMenu</tt>, it would have canceled the menu's display to the client.
*Menus, by default, have an exit button. We disabled this in our example.
*Our menu is set to display for 20 seconds. That means that if the client does not select an item within 20 seconds, the menu will be canceled. This is usually desired for menus that are for voting. Note that unlike AMX Mod X, you do not need to set a timer to make sure the menu will be ended.
*Although we created and destroyed a new Menu Handle, we didn't need to. It is perfectly acceptable to create the Handle once for the lifetime of the plugin.

Our finished menu and attached console output looks like this (I selected "Yes"):

[[Image:Basic_menu_1.PNG]]

==Basic Panel==
Now, let's rewrite our example to use Panels instead.

<pawn>public OnPluginStart()
{
RegConsoleCmd("panel_test1", Panel_Test1);
}

public PanelHandler1(Handle:menu, MenuAction:action, param1, param2)
{
if (action == MenuAction_Select)
{
PrintToConsole(param1, "You selected item: %d", param2);
} else if (action == MenuAction_Cancel) {
PrintToServer("Client %d's menu was cancelled. Reason: %d", param1, param2);
}
}

public Action:Panel_Test1(client, args)
{
new Handle:panel = CreatePanel();
SetPanelTitle(panel, "Do you like apples?");
DrawPanelItem(panel, "Yes");
DrawPanelItem(panel, "No");

SendPanelToClient(panel, client, PanelHandler1, 20);

CloseHandle(panel);

return Plugin_Handled;
}</pawn>

As you can see, Panels are significantly different.
*We can destroy the Panel as soon as we're done displaying it. We can create the Panel once and keep re-using it, but we can destroy it at any time without interrupting client menus.
*The Handler function gets much less data. Since panels are designed as a raw display, no "item" information is saved internally. Thus, the handler function only knows whether the display was canceled or whether (and what) numerical key was pressed.
*There is no automation. You cannot add more than a certain amount of selectable items to a Panel and get pagination. Automated control functionality requires using the heftier Menu object API.

Our finished display and console output looks like this (I selected "Yes"):

[[Image:Basic_panel_1.PNG]]

==Basic Paginated Menu==
Now, let's take a more advanced example -- pagination. Let's say we want to build a menu for changing the map. An easy way to do this is to read the <tt>maplist.txt</tt> file at the start of a plugin and build a menu out of it.

Since reading and parsing a file is an expensive operation, we only want to do this once per map. Thus we'll build the menu in <tt>OnMapStart</tt>, and we won't call <tt>CloseHandle</tt> until <tt>OnMapEnd</tt>.

Source code:
<pawn>new Handle:g_MapMenu = INVALID_HANDLE

public OnPluginStart()
{
RegConsoleCmd("menu_changemap", Command_ChangeMap);
}

public OnMapStart()
{
g_MapMenu = BuildMapMenu();
}

public OnMapEnd()
{
if (g_MapMenu != INVALID_HANDLE)
{
CloseHandle(g_MapMenu);
g_MapMenu = INVALID_HANDLE;
}
}

Handle:BuildMapMenu()
{
/* Open the file */
new Handle:file = OpenFile("maplist.txt", "rt");
if (file == INVALID_HANDLE)
{
return INVALID_HANDLE;
}

/* Create the menu Handle */
new Handle:menu = CreateMenu(Menu_ChangeMap);
new String:mapname[255];
while (!IsEndOfFile(file) && ReadFileLine(file, mapname, sizeof(mapname)))
{
if (mapname[0] == ';' || !IsCharAlpha(mapname[0]))
{
continue;
}
/* Cut off the name at any whitespace */
new len = strlen(mapname);
for (new i=0; i<len; i++);
{
if (IsCharSpace(mapname[i]))
{
mapname[i] = '\0';
break;
}
}
/* Check if the map is valid */
if (!IsMapValid(mapname))
{
continue;
}
/* Add it to the menu */
AddMenuItem(menu, mapname, mapname);
}
/* Make sure we close the file! */
CloseHandle(file);

/* Finally, set the title */
SetMenuTitle(menu, "Please select a map:");

return menu;
}

public Menu_ChangeMap(Handle:menu, MenuAction:action, param1, param2)
{
if (action == MenuAction_Select)
{
new String:info[32];

/* Get item info */
new bool:found = GetMenuItem(menu, param2, info, sizeof(info));

/* Tell the client */
PrintToConsole(param1, "You selected item: %d (found? %d info: %s)", param2, found, info);

/* Change the map */
ServerCommand("changelevel %s", info);
}
}

public Action:Command_ChangeMap(client, args)
{
if (g_MapMenu == INVALID_HANDLE)
{
PrintToConsole(client, "The maplist.txt file was not found!");
return Plugin_Handled;
}

DisplayMenu(g_MapMenu, client, MENU_TIME_FOREVER);

return Plugin_Handled;
}</pawn>

This menu results in many selections (my <tt>maplist.txt</tt> file had around 18 maps). So, our final menu has 3 pages, which side by side, look like:

[[Image:Basic_menu_2_page1.PNG]]
[[Image:Basic_menu_2_page2.PNG]]
[[Image:Basic_menu_2_page3.PNG]]

Finally, the console output printed this before the map changed to my selection, <tt>cs_office</tt>:
<pre>You selected item: 8 (found? 1 info: cs_office)</pre>

Displaying and designing this Menu with a raw <tt>ShowMenu</tt> message or <tt>Panel</tt> API would be very time consuming and difficult. We would have to keep track of all the items in an array of hardcoded size, pages which the user is viewing, and write a function which calculated item selection based on current page and key press. The Menu system, thankfully, handles all of this for you.

'''Notes:'''
*Control options which are not available are not drawn. For example, in the first page, you cannot go "back," and in the last page, you cannot go "next." Despite this, the menu API tries to keep each the interface as consistent as possible. Thus, visually, each navigational control is always in the same position.
*Although we specified no time out for our menu, if we had placed a timeout, flipping through pages does not affect the overall time. For example, if we had a timeout of 20, each successive page flip would continue to detract from the overall display time, rather than restart the allowed hold time back to 20.
*If we had disabled the Exit button, options 8 and 9 would still be "Back" and "Next," respectively.
*Again, we did not free the Menu Handle in <tt>MenuAction_End</tt>. This is because our menu is global/static, and we don't want to rebuild it every time.
*These images show "Back." In SourceMod revisions 1011 and higher, "Back" is changed to "Previous," and "Back" is reserved for the special "ExitBack" functionality.

=Voting=
SourceMod also has API for displaying menus as votable choices to more than one client. SourceMod automatically handles selecting an item and randomly picking a tie-breaker. The voting API adds two new <tt>MenuAction</tt> values, which for vote displays, are '''always''' passed:

*<tt>MenuAction_VoteStart</tt>: Fired after <tt>MenuAction_Start</tt> when the voting has officially started.
*<tt>MenuAction_VoteEnd</tt>: Fired when all clients have either voted or cancelled their vote menu. The chosen item is passed through <tt>param1</tt>. This is fired '''before''' <tt>MenuAction_End</tt>. It is important to note that it does not supercede <tt>MenuAction_End</tt>, nor is it the same thing. Menus should never be destroyed in <tt>MenuAction_VoteEnd</tt>. '''Note:''' This is not called if <tt>SetVoteResultCallback</tt>() is used.
*<tt>MenuAction_VoteCancel</tt>: Fired if the menu is cancelled while the vote is in progress. If this is called, <tt>MenuAction_VoteEnd</tt> or the result callback will not be called, but <tt>MenuAction_End</tt> will be afterwards. A vote cancellation reason is passed in <tt>param1</tt>.

The voting system extends overall menus with two additional properties:
*Only one vote can be active at a time. You must call <tt>IsVoteInProgress</tt>() or else <tt>VoteMenu</tt>() will fail.
*If a client votes and then disconnects while the vote is still active, the client's vote will be invalidated.

The example below shows has to create a function called <tt>DoVoteMenu()</tt> which will ask all clients whether or not they would like to change to the given map.

==Simple Vote==
<pawn>public Handle_VoteMenu(Handle:menu, MenuAction:action, param1, param2)
{
if (action == MenuAction_End)
{
/* This is called after VoteEnd */
CloseHandle(menu);
} else if (action == MenuAction_VoteEnd) {
/* 0=yes, 1=no */
if (param1 == 0)
{
new String:map[64];
GetMenuItem(menu, param1, map, sizeof(map));
ServerCommand("changelevel %s", map);
}
}
}

DoVoteMenu(const String:map[])
{
if (IsVoteInProgress())
{
return;
}

new Handle:menu = CreateMenu(Handle_VoteMenu);
SetMenuTitle(menu, "Change map to: %s?", map);
AddMenuItem(menu, map, "Yes");
AddMenuItem(menu, "no", "No");
SetMenuExitButton(menu, false);
VoteMenuToAll(menu, 20);
}</pawn>

==Advanced Voting==
If you need more information about voting results than <tt>MenuAction_VoteEnd</tt> gives you, you can choose to have a different callback invoked. The new callback will provide much more information, but at a price: <tt>MenuAction_VoteEnd</tt> will not be called, and you will have to decide how to interpret the results. This is done via <tt>SetVoteResultCallback</tt>().

Example:
<pawn>public Handle_VoteMenu(Handle:menu, MenuAction:action, param1, param2)
{
if (action == MenuAction_End)
{
/* This is called after VoteEnd */
CloseHandle(menu);
}
}

public Handle_VoteResults(Handle:menu,
num_votes,
num_clients,
const client_info[][2],
num_items,
const item_info[][2])
{
/* See if there were multiple winners */
new winner = 0;
if (num_items > 1
&& (item_info[0][VOTEINFO_ITEM_VOTES] == item_info[1][VOTEINFO_ITEM_VOTES]))
{
winner = GetRandomInt(0, 1);
}

new String:map[64];
GetMenuItem(menu, item_info[winner][VOTEINFO_ITEM_INDEX], map, sizeof(map));
ServerCommand("changelevel %s", map);
}

DoVoteMenu(const String:map[])
{
if (IsVoteInProgress())
{
return;
}

new Handle:menu = CreateMenu(Handle_VoteMenu);
SetVoteResultCallback(menu, Handle_VoteResults);
SetMenuTitle(menu, "Change map to: %s?", map);
AddMenuItem(menu, map, "Yes");
AddMenuItem(menu, "no", "No");
SetMenuExitButton(menu, false);
VoteMenuToAll(menu, 20);
}</pawn>

=ExitBack=
ExitBack is a special term to refer to the "ExitBack Button." This button is disabled by default. Normally, paginated menus have no "Previous" item for the first page. If the "ExitBack" button is enabled, the "Previous" item will show up as "Back."

Selecting the "ExitBack" option will exit the menu with <tt>MenuCancel_ExitBack</tt> and <tt>MenuEnd_ExitBack</tt>. The functionality of this is the same as a normal menu exit internally; extra functionality must be defined through the callbacks.

=Closing Menu Handles=
It is only necessary to close a menu handle on <tt>MenuAction_End</tt>. The <tt>MenuAction_End</tt> is done every time a menu is closed and no longer needed.

=Translations=
It is possible to dynamically translate menus to each player through the <tt>MenuAction_DisplayItem</tt> callback. A special native, <tt>RedrawMenuItem</tt>, is used to transform the text while inside the callback. Let's redo the vote example from earlier to be translated:

<pawn>public Handle_VoteMenu(Handle:menu, MenuAction:action, param1, param2)
{
if (action == MenuAction_End)
{
/* This is called after VoteEnd */
CloseHandle(menu);
} else if (action == MenuAction_VoteEnd) {
/* 0=yes, 1=no */
if (param1 == 0)
{
new String:map[64];
GetMenuItem(menu, param1, map, sizeof(map));
ServerCommand("changelevel %s", map);
}
} else if (action == MenuAction_DisplayItem) {
/* Get the display string, we'll use it as a translation phrase */
decl String:display[64];
GetMenuItem(menu, param2, "", 0, _, display, sizeof(display));

/* Translate the string to the client's language */
decl String:buffer[255];
Format(buffer, sizeof(buffer), "%T", display, param1);

/* Override the text */
return RedrawMenuItem(buffer);
} else if (action == MenuAction_Display) {
/* Panel Handle is the second parameter */
new Handle:panel = Handle:param2;

/* Get the map name we're changing to from the first item */
decl String:map[64];
GetMenuItem(menu, 0, map, sizeof(map));

/* Translate to our phrase */
decl String:buffer[255];
Format(buffer, sizeof(buffer), "%T", "Change map to?", client, map);

SetPanelTitle(panel, buffer);
}
}

DoVoteMenu(const String:map[])
{
if (IsVoteInProgress())
{
return;
}

new Handle:menu = CreateMenu(Handle_VoteMenu, MenuAction_DisplayItem|MenuAction_Display);
SetMenuTitle(menu, "Change map to: %s?", map);
AddMenuItem(menu, map, "Yes");
AddMenuItem(menu, "no", "No");
SetMenuExitButton(menu, false);
VoteMenuToAll(menu, 20);
}</pawn>

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

{{LanguageSwitch}}

Menu API (SourceMod)

2009-08-12T03:37:24Z

Applecorc: /* Simple Vote */ added semi-colon

SourceMod has an extensive API for building and displaying menus to clients. Unlike AMX Mod X, this API is highly state driven. Menus are based on callbacks which are guaranteed to be fired.

For C++, the Menu API can be found in <tt>public/IMenuManager.h</tt>. For SourcePawn, it is in <tt>plugins/include/menus.inc</tt>.

=Objects=
The SourceMod Menu System is based on an object oriented hierarchy. Understanding this hierarchy, even for scripting, is critical to using menus effectively.

==Styles==
The top level object is a ''MenuStyle'' (<tt>IMenuStyle</tt> in C++). Styles describe a unique menu system. There are two such styles built into SourceMod:
*Valve Style, also called "ESC" menus; 8 items per page, no raw/disabled text can be rendered
*Radio Style, also called "AMX" menus; 10 items per page, raw/disabled text can be rendered

Each MenuStyle has its own rules and properties. You can think of them as existing on separate "channels." For example, two different menus can exist on a player's screen as both a Valve menu and a Radio menu at the same time, and SourceMod will be able to manage both without any problems. This is because each style keeps track of its own menus separately.

==Panels==
Menu displays are drawn with a lower level interface called ''Panels'' (<tt>IMenuPanel</tt> in C++). Panels describe exactly one chunk of display text. Both selectable items and raw text can be added to a panel as long as its parent style supports the contents you're trying to draw. For example, the Valve style does not support drawing raw text or disabled items. But with a Radio-style Panel, you can display a large amount of on-screen data in your own format.

Panels are considered temporary objects. They are created, rendered, displayed, and destroyed. Although they can be saved indefinitely, it is not necessary to do so.

Valve Style drawing rules/limitations:
*Max items per page is 8.
*Disabled items cannot be drawn.
*Raw text cannot be drawn.
*Spacers do not add a space/newline, giving a "cramped" feel.
*Users must press "ESC" or be at their console to view the menu.

Radio Style drawing rules/limitations:
*Max items per page is 10.
*Titles appear white; items appear yellow, unless disabled, in which case they are white.
*The 0th item is always white. For consistency, this means navigational controls explained in the next section are always white, and simply not drawn if disabled.

==Menus==
Lastly, there are plain ''Menus'' (<tt>IBaseMenu</tt> in C++). These are helper objects designed for storing a menu based on selectable items. Unlike low-level panels, menus are containers for '''items''', and can only contain items which are selectable (i.e., do not contain raw text). They fall into two categories:
*Non-paginated: The menu can only have a certain number of items on it, and no control/navigation options will be added, except for an "Exit" button which will always be in the last position supported by the style.
**Valve Style maximum items: 8
**Radio Style maximum items: 10
*Paginated: The menu can have any number of items. When displayed, only a certain number of items will be drawn at a time. Automatic navigation controls are added so players can easily move back and forth to different "pages" of items in the menu.
**"Previous" is always drawn as the first navigation item, third from the last supported position. This will not be drawn if the menu only contains one page. If there are no previous pages, the text will not be drawn on either style; if possible, the menu will be padded so spacing is consistent.
***Valve Style position: 6
***Radio Style position: 8
**"Next" is always drawn as the second navigation item, second from the last supported position. This will not be drawn if the menu only contains one page. If there are no further pages, the text will not be drawn on either style; if possible, the menu will be padded so spacing is consistent.
***Valve Style position: 7
***Radio Style position: 9
**"Exit" is drawn if the menu has the exit button property set. It is always the last supported item position.
***Valve Style position: 8
***Radio Style position: 10

The purpose of Menus is to simplify the procedure of storing, drawing, and calculating the selection of items. Thus, menus do not allow for adding raw text, as that would considerably complicate the drawing algorithm. ''Note: The C++ API supports hooking <tt>IBaseMenu</tt> drawing procedures and adding raw text; this will be added to the scripting API soon.''

Internally, Menus are drawn via a ''RenderMenu'' algorithm. This algorithm creates a temporary panel and fills it with items from menus. This panel is then displayed to a client. The algorithm attempts to create a consistent feel across all menus, and across all styles. Thus any menu displayed via the <tt>IBaseMenu</tt> class, or <tt>Menu</tt> Handles, will look and act the same, and the Menu API is based off the Panel API.

=Callbacks=
==Overview==
Menus are a callback based system. Each callback represents an action that occurs during a ''menu display cycle''. A cycle consists of a number of notifications:
*Start notification.
**Display notification if the menu can be displayed to the client.
**Either an item select or menu cancel notification.
*End notification.

Since ''End'' signifies the end of a full display cycle, it is usually used to destroy temporary menus.

==Specification==
A detailed explanation of these events is below. For C++, an <tt>IBaseMenu</tt> pointer is always available. For SourcePawn, a <tt>Menu</tt> Handle and a <tt>MenuAction</tt> are always set in the <tt>MenuHandler</tt> callback. Unlike C++, the SourcePawn API allows certain actions to only be called if they are requested at menu creation time. This is an optimization. However, certain actions cannot be prevented from being called.

*'''Start'''. The menu has been acknowledged. This does not mean it will be displayed; however, it guarantees that "OnMenuEnd" will be called.
**<tt>OnMenuStart()</tt> in C++.
**<tt>MenuAction_Start</tt> in SourcePawn. This action is not triggered unless requested.
***<tt>param1</tt>: Ignored (always 0).
***<tt>param2</tt>: Ignored (always 0).
*'''Display'''. The menu is being displayed to a client.
**<tt>OnMenuDisplay()</tt> in C++. An <tt>IMenuPanel</tt> pointer and client index are available.
**<tt>MenuAction_Display</tt> in SourcePawn. This action is not triggered unless requested.
***<tt>param1</tt>: A client index.
***<tt>param2</tt>: A Handle to a menu panel.
*'''Select'''. An item on the menu has been selected. The item position given will be the position in the menu, rather than the key pressed (unless the menu is a raw panel).
**<tt>OnMenuSelect()</tt> in C++. A client index and item position are passed.
**<tt>MenuAction_Select</tt> in SourcePawn. This action is always triggerable, whether requested or not.
***<tt>param1</tt>: A client index.
***<tt>param2</tt>: An item position.
*'''Cancel'''. The menu's display to one client has been cancelled.
**<tt>OnMenuCancel()</tt> in C++. A reason for cancellation is provided.
**<tt>MenuAction_Cancel</tt> in SourcePawn. This action is always triggerable, whether requested or not.
***<tt>param1</tt>: A client index.
***<tt>param2</tt>: A menu cancellation reason code.
*'''End'''. The menu's display cycle has finished; this means that the "Start" action has occurred, and either "Select" or "Cancel" has occurred thereafter. This is typically where menu resources are removed/deleted.
**<tt>OnMenuEnd()</tt> in C++.
**<tt>MenuAction_End</tt> in SourcePawn. This action is always triggered, whether requested or not.
***<tt>param1</tt>: A menu end reason code.
***<tt>param2</tt>: If param1 was MenuEnd_Cancelled, this contains a menu cancellation reason code.

==Panels==
For panels, the callback rules change. Panels only receive two of the above callbacks, and it is guaranteed that only one of them will be called for a given display cycle. For C++, the <tt>IBaseMenu</tt> pointer will always be <tt>NULL</tt>. For SourcePawn, the menu Handle will always be <tt>INVALID_HANDLE</tt>.

*'''Select'''. A key has been pressed. This can be any number and should not be considered as reliably in bounds. For example, even if you only had 2 items in your panel, a client could trigger a key press of "43."
**<tt>OnMenuSelect()</tt> in C++. A client index and key number pressed are passed.
**<tt>MenuAction_Select</tt> in SourcePawn.
***<tt>param1</tt>: A client index.
***<tt>param2</tt>: Number of the key pressed.
*'''Cancel'''. The menu's display to one client has been cancelled.
**<tt>OnMenuCancel()</tt> in C++. A reason for cancellation is provided.
**<tt>MenuAction_Cancel</tt> in SourcePawn.
***<tt>param1</tt>: A client index.
***<tt>param2</tt>: A menu cancellation reason code.

=Examples=
First, let's start off with a very basic menu. We want the menu to look like this:

<pre>Do you like apples?
1. Yes
2. No</pre>

We'll draw this menu with both a basic Menu and a Panel to show the API differences.

==Basic Menu==
First, let's write our example using the Menu building API.

<pawn>public OnPluginStart()
{
RegConsoleCmd("menu_test1", Menu_Test1)
}

public MenuHandler1(Handle:menu, MenuAction:action, param1, param2)
{
/* If an option was selected, tell the client about the item. */
if (action == MenuAction_Select)
{
new String:info[32]
new bool:found = GetMenuItem(menu, param2, info, sizeof(info))
PrintToConsole(param1, "You selected item: %d (found? %d info: %s)", param2, found, info)
}
/* If the menu was cancelled, print a message to the server about it. */
else if (action == MenuAction_Cancel)
{
PrintToServer("Client %d's menu was cancelled. Reason: %d", param1, param2)
}
/* If the menu has ended, destroy it */
else if (action == MenuAction_End)
{
CloseHandle(menu)
}
}

public Action:Menu_Test1(client, args)
{
new Handle:menu = CreateMenu(MenuHandler1)
SetMenuTitle(menu, "Do you like apples?")
AddMenuItem(menu, "yes", "Yes")
AddMenuItem(menu, "no", "No")
SetMenuExitButton(menu, false)
DisplayMenu(menu, client, 20)

return Plugin_Handled
}</pawn>

Note a few very important points from this example:
*One of either <tt>Select</tt> or <tt>Cancel</tt> will always be sent to the action handler.
*<tt>End</tt> will always be sent to the action handler.
*We destroy our Menu in the <tt>End</tt> action, because our Handle is no longer needed. If we had destroyed the Menu after <tt>DisplayMenu</tt>, it would have canceled the menu's display to the client.
*Menus, by default, have an exit button. We disabled this in our example.
*Our menu is set to display for 20 seconds. That means that if the client does not select an item within 20 seconds, the menu will be canceled. This is usually desired for menus that are for voting. Note that unlike AMX Mod X, you do not need to set a timer to make sure the menu will be ended.
*Although we created and destroyed a new Menu Handle, we didn't need to. It is perfectly acceptable to create the Handle once for the lifetime of the plugin.

Our finished menu and attached console output looks like this (I selected "Yes"):

[[Image:Basic_menu_1.PNG]]

==Basic Panel==
Now, let's rewrite our example to use Panels instead.

<pawn>public OnPluginStart()
{
RegConsoleCmd("panel_test1", Panel_Test1)
}

public PanelHandler1(Handle:menu, MenuAction:action, param1, param2)
{
if (action == MenuAction_Select)
{
PrintToConsole(param1, "You selected item: %d", param2)
} else if (action == MenuAction_Cancel) {
PrintToServer("Client %d's menu was cancelled. Reason: %d", param1, param2)
}
}

public Action:Panel_Test1(client, args)
{
new Handle:panel = CreatePanel();
SetPanelTitle(panel, "Do you like apples?")
DrawPanelItem(panel, "Yes")
DrawPanelItem(panel, "No")

SendPanelToClient(panel, client, PanelHandler1, 20)

CloseHandle(panel)

return Plugin_Handled
}</pawn>

As you can see, Panels are significantly different.
*We can destroy the Panel as soon as we're done displaying it. We can create the Panel once and keep re-using it, but we can destroy it at any time without interrupting client menus.
*The Handler function gets much less data. Since panels are designed as a raw display, no "item" information is saved internally. Thus, the handler function only knows whether the display was canceled or whether (and what) numerical key was pressed.
*There is no automation. You cannot add more than a certain amount of selectable items to a Panel and get pagination. Automated control functionality requires using the heftier Menu object API.

Our finished display and console output looks like this (I selected "Yes"):

[[Image:Basic_panel_1.PNG]]

==Basic Paginated Menu==
Now, let's take a more advanced example -- pagination. Let's say we want to build a menu for changing the map. An easy way to do this is to read the <tt>maplist.txt</tt> file at the start of a plugin and build a menu out of it.

Since reading and parsing a file is an expensive operation, we only want to do this once per map. Thus we'll build the menu in <tt>OnMapStart</tt>, and we won't call <tt>CloseHandle</tt> until <tt>OnMapEnd</tt>.

Source code:
<pawn>new Handle:g_MapMenu = INVALID_HANDLE

public OnPluginStart()
{
RegConsoleCmd("menu_changemap", Command_ChangeMap)
}

public OnMapStart()
{
g_MapMenu = BuildMapMenu()
}

public OnMapEnd()
{
if (g_MapMenu != INVALID_HANDLE)
{
CloseHandle(g_MapMenu)
g_MapMenu = INVALID_HANDLE
}
}

Handle:BuildMapMenu()
{
/* Open the file */
new Handle:file = OpenFile("maplist.txt", "rt")
if (file == INVALID_HANDLE)
{
return INVALID_HANDLE
}

/* Create the menu Handle */
new Handle:menu = CreateMenu(Menu_ChangeMap);
new String:mapname[255]
while (!IsEndOfFile(file) && ReadFileLine(file, mapname, sizeof(mapname)))
{
if (mapname[0] == ';' || !IsCharAlpha(mapname[0]))
{
continue
}
/* Cut off the name at any whitespace */
new len = strlen(mapname)
for (new i=0; i<len; i++)
{
if (IsCharSpace(mapname[i]))
{
mapname[i] = '\0'
break
}
}
/* Check if the map is valid */
if (!IsMapValid(mapname))
{
continue
}
/* Add it to the menu */
AddMenuItem(menu, mapname, mapname)
}
/* Make sure we close the file! */
CloseHandle(file)

/* Finally, set the title */
SetMenuTitle(menu, "Please select a map:")

return menu
}

public Menu_ChangeMap(Handle:menu, MenuAction:action, param1, param2)
{
if (action == MenuAction_Select)
{
new String:info[32]

/* Get item info */
new bool:found = GetMenuItem(menu, param2, info, sizeof(info))

/* Tell the client */
PrintToConsole(param1, "You selected item: %d (found? %d info: %s)", param2, found, info)

/* Change the map */
ServerCommand("changelevel %s", info)
}
}

public Action:Command_ChangeMap(client, args)
{
if (g_MapMenu == INVALID_HANDLE)
{
PrintToConsole(client, "The maplist.txt file was not found!")
return Plugin_Handled
}

DisplayMenu(g_MapMenu, client, MENU_TIME_FOREVER)

return Plugin_Handled
}</pawn>

This menu results in many selections (my <tt>maplist.txt</tt> file had around 18 maps). So, our final menu has 3 pages, which side by side, look like:

[[Image:Basic_menu_2_page1.PNG]]
[[Image:Basic_menu_2_page2.PNG]]
[[Image:Basic_menu_2_page3.PNG]]

Finally, the console output printed this before the map changed to my selection, <tt>cs_office</tt>:
<pre>You selected item: 8 (found? 1 info: cs_office)</pre>

Displaying and designing this Menu with a raw <tt>ShowMenu</tt> message or <tt>Panel</tt> API would be very time consuming and difficult. We would have to keep track of all the items in an array of hardcoded size, pages which the user is viewing, and write a function which calculated item selection based on current page and key press. The Menu system, thankfully, handles all of this for you.

'''Notes:'''
*Control options which are not available are not drawn. For example, in the first page, you cannot go "back," and in the last page, you cannot go "next." Despite this, the menu API tries to keep each the interface as consistent as possible. Thus, visually, each navigational control is always in the same position.
*Although we specified no time out for our menu, if we had placed a timeout, flipping through pages does not affect the overall time. For example, if we had a timeout of 20, each successive page flip would continue to detract from the overall display time, rather than restart the allowed hold time back to 20.
*If we had disabled the Exit button, options 8 and 9 would still be "Back" and "Next," respectively.
*Again, we did not free the Menu Handle in <tt>MenuAction_End</tt>. This is because our menu is global/static, and we don't want to rebuild it every time.
*These images show "Back." In SourceMod revisions 1011 and higher, "Back" is changed to "Previous," and "Back" is reserved for the special "ExitBack" functionality.

=Voting=
SourceMod also has API for displaying menus as votable choices to more than one client. SourceMod automatically handles selecting an item and randomly picking a tie-breaker. The voting API adds two new <tt>MenuAction</tt> values, which for vote displays, are '''always''' passed:

*<tt>MenuAction_VoteStart</tt>: Fired after <tt>MenuAction_Start</tt> when the voting has officially started.
*<tt>MenuAction_VoteEnd</tt>: Fired when all clients have either voted or cancelled their vote menu. The chosen item is passed through <tt>param1</tt>. This is fired '''before''' <tt>MenuAction_End</tt>. It is important to note that it does not supercede <tt>MenuAction_End</tt>, nor is it the same thing. Menus should never be destroyed in <tt>MenuAction_VoteEnd</tt>. '''Note:''' This is not called if <tt>SetVoteResultCallback</tt>() is used.
*<tt>MenuAction_VoteCancel</tt>: Fired if the menu is cancelled while the vote is in progress. If this is called, <tt>MenuAction_VoteEnd</tt> or the result callback will not be called, but <tt>MenuAction_End</tt> will be afterwards. A vote cancellation reason is passed in <tt>param1</tt>.

The voting system extends overall menus with two additional properties:
*Only one vote can be active at a time. You must call <tt>IsVoteInProgress</tt>() or else <tt>VoteMenu</tt>() will fail.
*If a client votes and then disconnects while the vote is still active, the client's vote will be invalidated.

The example below shows has to create a function called <tt>DoVoteMenu()</tt> which will ask all clients whether or not they would like to change to the given map.

==Simple Vote==
<pawn>public Handle_VoteMenu(Handle:menu, MenuAction:action, param1, param2)
{
if (action == MenuAction_End)
{
/* This is called after VoteEnd */
CloseHandle(menu);
} else if (action == MenuAction_VoteEnd) {
/* 0=yes, 1=no */
if (param1 == 0)
{
new String:map[64];
GetMenuItem(menu, param1, map, sizeof(map));
ServerCommand("changelevel %s", map);
}
}
}

DoVoteMenu(const String:map[])
{
if (IsVoteInProgress())
{
return;
}

new Handle:menu = CreateMenu(Handle_VoteMenu);
SetMenuTitle(menu, "Change map to: %s?", map);
AddMenuItem(menu, map, "Yes");
AddMenuItem(menu, "no", "No");
SetMenuExitButton(menu, false);
VoteMenuToAll(menu, 20);
}</pawn>

==Advanced Voting==
If you need more information about voting results than <tt>MenuAction_VoteEnd</tt> gives you, you can choose to have a different callback invoked. The new callback will provide much more information, but at a price: <tt>MenuAction_VoteEnd</tt> will not be called, and you will have to decide how to interpret the results. This is done via <tt>SetVoteResultCallback</tt>().

Example:
<pawn>public Handle_VoteMenu(Handle:menu, MenuAction:action, param1, param2)
{
if (action == MenuAction_End)
{
/* This is called after VoteEnd */
CloseHandle(menu);
}
}

public Handle_VoteResults(Handle:menu,
num_votes,
num_clients,
const client_info[][2],
num_items,
const item_info[][2])
{
/* See if there were multiple winners */
new winner = 0;
if (num_items > 1
&& (item_info[0][VOTEINFO_ITEM_VOTES] == item_info[1][VOTEINFO_ITEM_VOTES]))
{
winner = GetRandomInt(0, 1);
}

new String:map[64]
GetMenuItem(menu, item_info[winner][VOTEINFO_ITEM_INDEX], map, sizeof(map))
ServerCommand("changelevel %s", map)
}

DoVoteMenu(const String:map[])
{
if (IsVoteInProgress())
{
return;
}

new Handle:menu = CreateMenu(Handle_VoteMenu)
SetVoteResultCallback(menu, Handle_VoteResults)
SetMenuTitle(menu, "Change map to: %s?", map)
AddMenuItem(menu, map, "Yes")
AddMenuItem(menu, "no", "No")
SetMenuExitButton(menu, false)
VoteMenuToAll(menu, 20);
}</pawn>

=ExitBack=
ExitBack is a special term to refer to the "ExitBack Button." This button is disabled by default. Normally, paginated menus have no "Previous" item for the first page. If the "ExitBack" button is enabled, the "Previous" item will show up as "Back."

Selecting the "ExitBack" option will exit the menu with <tt>MenuCancel_ExitBack</tt> and <tt>MenuEnd_ExitBack</tt>. The functionality of this is the same as a normal menu exit internally; extra functionality must be defined through the callbacks.

=Closing Menu Handles=
It is only necessary to close a menu handle on <tt>MenuAction_End</tt>. The <tt>MenuAction_End</tt> is done every time a menu is closed and no longer needed.

=Translations=
It is possible to dynamically translate menus to each player through the <tt>MenuAction_DisplayItem</tt> callback. A special native, <tt>RedrawMenuItem</tt>, is used to transform the text while inside the callback. Let's redo the vote example from earlier to be translated:

<pawn>public Handle_VoteMenu(Handle:menu, MenuAction:action, param1, param2)
{
if (action == MenuAction_End)
{
/* This is called after VoteEnd */
CloseHandle(menu);
} else if (action == MenuAction_VoteEnd) {
/* 0=yes, 1=no */
if (param1 == 0)
{
new String:map[64]
GetMenuItem(menu, param1, map, sizeof(map))
ServerCommand("changelevel %s", map);
}
} else if (action == MenuAction_DisplayItem) {
/* Get the display string, we'll use it as a translation phrase */
decl String:display[64];
GetMenuItem(menu, param2, "", 0, _, display, sizeof(display));

/* Translate the string to the client's language */
decl String:buffer[255];
Format(buffer, sizeof(buffer), "%T", display, param1);

/* Override the text */
return RedrawMenuItem(buffer);
} else if (action == MenuAction_Display) {
/* Panel Handle is the second parameter */
new Handle:panel = Handle:param2;

/* Get the map name we're changing to from the first item */
decl String:map[64];
GetMenuItem(menu, 0, map, sizeof(map));

/* Translate to our phrase */
decl String:buffer[255];
Format(buffer, sizeof(buffer), "%T", "Change map to?", client, map);

SetPanelTitle(panel, buffer);
}
}

DoVoteMenu(const String:map[])
{
if (IsVoteInProgress())
{
return;
}

new Handle:menu = CreateMenu(Handle_VoteMenu, MenuAction_DisplayItem|MenuAction_Display)
SetMenuTitle(menu, "Change map to: %s?", map)
AddMenuItem(menu, map, "Yes")
AddMenuItem(menu, "no", "No")
SetMenuExitButton(menu, false)
VoteMenuToAll(menu, 20);
}</pawn>

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

{{LanguageSwitch}}

Building SourceMod

2009-08-11T22:05:10Z

Applecorc: /* Getting the Files */ Added link to L4D SDK

Compiling SourceMod is not difficult, but requires a number of prerequisites. This article details the requirements and steps to being able to build working SourceMod binaries. These directions may change any time and may be updated as SourceMod's build process improves.

'''Note:''' You cannot use MingW to build working SourceMod Windows binaries. It is not ABI compatible with Visual C++ which is what Valve uses for the Source engine. You can only use GCC to build Linux binaries.

=Requirements=

==Windows==
*Microsoft Visual C++ 2008 (Express or higher) is supported and used for official builds.
*Microsoft Visual C++ 2005 (Express or higher) is unsupported.
*Microsoft Visual C++ 2003 7.1 or higher may not build out-of-box, but can build compatible binaries.
*Microsoft Visual C++ 2003 7.0 or lower '''cannot''' be used.

If you are installing Visual C++ 2005 Express, it may not come with Microsoft's Platform SDK installed. If this is the case, you must manually install the Platform SDK. You can find directions on how to do this and test your setup [http://www.microsoft.com/express/2005/platformsdk/default.aspx here]. Visual C++ 2008 "streamlines" the Platform SDK installation according to Microsoft.

==Linux==
For Linux, SourceMod requires the GNU C/C++ Compiler (from GCC):
*Version 4.1 is used for official binaries and is guaranteed to build.
*Versions 3.4 through 4.2 are guaranteed to be binary (ABI) compatible, although SourceMod may not necessarily build out-of-box against them.
*Any GCC version below 3.4 '''cannot''' be used.

==CPU==
SourceMod is strictly a 32-bit x86 (IA32) product. You should not try to force a compiler to build 64-bit binaries of SourceMod.

Your CPU and its compiler must support SSE in order to build SourceMod. To build without needing or having a dependency against SSE, please see the [[Compiling SourceMod#Removing SSE|Removing SSE]] section near the bottom.

Approximate compiling times for SourceMod's Core are roughly:
*Windows, Core 2 Quad E6600: 30 seconds (using /MP)
*Windows, Core 2 Duo E6600: 75 seconds
*Windows, Centrino 1.8GHz: 5 minutes
*Linux, Core 2 Duo E6600: <= 1 minute
*Linux, P3 Dual 500MHz: >= 7 minutes

=Setup=
This section describes how to set up your computer for compiling.

==Getting the Files==
This section describes which files you must obtain and how to obtain them. Do not worry about where to place them yet -- that will be discussed on a per-platform basis. You can download the files anywhere you'd like.

The recommended method of getting the required files is via [http://subversion.tigris.org/ Subversion]. We have our own [[Subversion Tutorial]] if you prefer that method. Although you do not need both HL2SDK versions (unless you wish to build binaries against both), you do need both Metamod:Source versions. Extensions don't necessarily require Metamod:Source (or even the Source Engine) but its template library is used extensively in SourceMod.

*SourceMod. For full download options, see the [http://www.sourcemod.net/downloads.php SourceMod Downloads] page. Obviously, you must download the source code and not a binary package.
*HL2SDK Original. As of this writing (Sep 2008) this engine is used for most Source games, except for TF2, GMod10, and DoD:S. Repository: [http://hg.alliedmods.net/hl2sdk hl2sdk]
*HL2SDK OrangeBox. As of this writing (Sep 2008) this engine is used TF2, GMod10, and DoD:S. Repository: [http://hg.alliedmods.net/hl2sdk-ob hl2sdk-ob]
*HL2SDK Left4Dead. This engine is used for L4D. Repository: [http://hg.alliedmods.net/hl2sdk-l4d hl2sdk-l4d]
*Metamod:Source Source Code. Visit [http://www.metamodsource.net/?go=downloads Metamod:Source downloads]. Right now SourceMod builds against Metamod:Source 1.7.

'''Note''' that when we refer to "Metamod:Source" in this article, we are referring to its source code tree, not a binary package.

If you intend to compile the MySQL extension, you must also download MySQL 5.0. You can use any version. For simplicity, here are the versions we use:
*Linux: We use the 5.0.45 binary from the "[http://dev.mysql.com/downloads/mysql/5.0.html#linux Linux (non RPM packages)]" for "Linux (x86)." You can also use [http://dev.mysql.com/get/Downloads/MySQL-5.0/mysql-5.0.45-linux-i686-glibc23.tar.gz/from/pick this direct link] (may not be valid in the future).
*Windows: Due to a MySQL build change we use 5.0.24a which is an older download. The file name was "mysql-5.0.24a-win32.zip," if you can't find it you can use this [http://www.bailopan.net/mysql-5.0.24a-win32.zip direct link] (may not be valid in the future).

You can remove all folders from the distribution except for the "lib" and "include" folders which comprise the MySQL SDK.

==Linux==
As of this writing, SourceMod's Makefiles are hardcoded to use a binary called "gcc-4.1" You can override this, for example:
<pre>make CPP=gcc</pre>

Otherwise, you can also just create a symlink:
<pre>sudo ln -s /usr/bin/gcc /usr/bin/gcc-4.1</pre>

Note that you must use <tt>gcc</tt> and not <tt>g++</tt>.

SourceMod's Makefiles have strict directory organizational rules. You must have a top-level folder. For this document, we'll assume it is called <tt>sourcemod</tt>, though it can be named anything. The layout of <tt>sourcemod</tt> must be:
*<tt>sourcemod</tt>/
**<tt>hl2sdk</tt> - symlink or folder containing the HL2SDK
**<tt>hl2sdk-ob</tt> - symlink or folder containing the HL2SDK for Orange Box/TF
**<tt>mmsource-1.7</tt> - symlink or folder containing any Metamod:Source version 1.7 or higher.
**<tt>sourcemod-central</tt> - folder containing SourceMod's source code tree. This can be named anything, as long as it's a valid SourceMod tree (like [http://hg.alliedmods.net/sourcemod-central sourcemod-central]). You can also use [http://hg.alliedmods.net/sourcemod-1.1 sourcemod-1.1].
**<tt>mysql-5.0</tt> - symlink or folder containing a MySQL 5.0 distribution

If you are using a 64-bit version of Linux, you may need to install extra packages to be able to compile SourceMod. On Debian-based distros, these are typically:
<pre>
#prerequisites
#apt-get install g++-4.1 gcc-4.1 make subversion
#apt-get instal libz libz-dev
#only needed if you want to use the build tool
#apt-get install mono mono-devel
#32-bit support
apt-get install ia32-libs
apt-get install lib32z1 lib32z1-dev
apt-get install libc6-dev-i386 libc6-i386
</pre>

==Windows==
On Windows we don't require a particular directory layout. Instead, environment variables are used. The directions below apply to Windows XP, and are assumed to be similar for other versions of Windows.
*Open the Control Panel (for example, via Start -> Settings).
*Open the System control. If you don't see it, you may need to switch to "Classic view" (either via the left-hand pane or by going to Tools -> Folder Options).
*Click the Advanced tab.
*Click the Environment Variables button.

You can add your environment variables to either your User settings or your System settings. Create a new variable for each item in the list below. The item names are in <tt>fixed-width font</tt> and their value descriptions follow.
*<tt>MMSOURCE17</tt> - Path to Metamod:Source 1.7+
*<tt>HL2SDK</tt> - Path to HL2SDK Ep1/Original
*<tt>HL2SDKOB</tt> - Path to HL2SDK Ep2/OrangeBox

=Building=
SourceMod has two types of binaries: those with an engine/MM:S dependence, and those without ("normal" binaries). Normal binaries have two modes:
*<tt>Release</tt> - Optimized binary for release.
*<tt>Debug</tt> - Unoptimized binary with debugging checks.

Engine/MM:S dependent binaries have three build modes, each paired with either Release or Debug, meaning there are six build options total. They are:
*<tt>Original</tt> - Building against MM:S 1.4 API with HL2SDK
*<tt>Episode2</tt> - Building against MM:S 1.6 API with HL2SDK-OB or higher

==Linux==
For both Normal and Engine/MM:S dependent binaries, the object files and the final binary are placed in a folder called <tt>Release</tt> or <tt>Debug</tt> (in the same level as the Makefile) depending on which building mechanism you chose.

'''Note:''' Our Makefiles are not set up to detect changes in header files. If you change a header file, you must clean your build.

===Normal Binaries===
For normal binaries, you can build simply with:

<pre>make</pre>

You can clean stale object files with:
<pre>make clean</pre>

Or build debug builds with:
<pre>make DEBUG=true</pre>

===Dependent Binaries===
Binaries that have an Engine or MM:S dependency require one extra parameter, <tt>ENGINE</tt>. It must be either <tt>orangebox</tt> or <tt>original</tt>. For example, to build a TF-compatible binary in debug mode:

<pre>make ENGINE=orangebox DEBUG=true</pre>

Dependent binaries are dropped into one of the following folders:
*Debug.original
*Debug.orangebox
*Release.original
*Release.orangebox

==Windows==
Windows project files end with <tt>.vcproj</tt> and are found in an <tt>msvc8</tt> folder that resides inside each binary's main source folder. For example, Core is located in <tt>core/msvc8/sourcemod_mm.vcproj</tt>.

Once the file is opened, you can select which build to use by going to Build -> Configuration Manager. Normal binaries have simply "Debug" and "Release." Dependent binaries have the following builds:
*Debug - Old Metamod
*Debug - Episode 2
*Release - Old Metamod
*Release - Episode 2

'''Note''' that dependent binaries will have plain "Debug" and "Release" builds. These should not be used as they are not configured.

Once you have selected a configuration, you can compile by going to Build -> Build Solution. The binaries and object files will be written to a folder inside <tt>msvc8</tt> named after the full configuration name. For example, using "Debug - Old Metamod" with the "sdktools" extension will result in the binary: <tt>extensions/sdktools/msvc8/Debug - Old Metamod/sdktools.ext.dll</tt>

'''Note:''' Visual Studio detects changes to header files intelligently. It is usually not necessary to rebuild a solution.

=Binary Organization=
Although SourceMod has a somewhat unified building mechanism, each of the binaries has a different purpose. They can be separated into the following classes:

*Core-Related: Binaries which are required or loaded intrinsically by Core.
*Extensions: Binaries which are loaded via the extension mechanism.
*External: Binaries which are standalone or unrelated to SourceMod's live operation (for example, the compiler).

This article is only concerned with the first two types.

==Core-Related Binaries==
Binaries related to Core are spread throughout the source code tree. They are always placed in <tt>sourcemod/bin</tt> for packaging. The projects files related to Core are:

*<tt>loader</tt> - This is a very small wrapper binary responsible for detecting the MM:S version and game engine, and deciding which SourceMod version to load. The output binary is <tt>sourcemod_mm_i486.so</tt> or <tt>sourcemod_mm.dll</tt>.
*<tt>core</tt> - This is Core itself, and is a dependent binary. It has three outputs:
**Original: <tt>sourcemod.1.ep1.so</tt>/<tt>sourcemod.1.ep1.dll</tt>
**Episode 1: <tt>sourcemod.1.ep1.so</tt>/<tt>sourcemod.2.ep1.dll</tt> (unsupported, not packaged)
**Episode 2: <tt>sourcemod.1.ep1.so</tt>/<tt>sourcemod.2.ep2.dll</tt>
*<tt>sourcepawn/jit/x86</tt> - This is the SourcePawn JIT for generating IA32/x86 instructions from <tt>.smx</tt> files. Currently the source code for this is not made available. It is built as <tt>sourcepawn.jit.x86.so</tt>/<tt>sourcepawn.jit.x86.dll</tt>.

It is technically not necessary to use the loader. It is provided as a convenience so users do not have to perform extra steps while installing SourceMod. However, it is highly recommend that you do use it in order to maintain similarity with the default SourceMod package.

==Extensions==
Extensions are found in the <tt>extensions</tt> folder of the source tree. SDKTools, Cstrike, and the upcoming TF extension are engine/MM:S dependent (and the rest are generally not).

Extensions always are named <tt>name.ext.so</tt> or <tt>name.ext.dll</tt> where <tt>name</tt> is a unique identifier. This is true even of dependent binaries.

When loading extensions, SourceMod looks in two separate folders. First, it checks the ''dependent extension folder'', which is <tt>extensions/auto.x.y</tt> where <tt>x</tt> is the MM:S version (1 for 1.4, 2 for 1.6) and <tt>y</tt> is the Engine version (1 for Original/Ep1, 2 for Ep2/OrangeBox). If no matching extension is found there, it looks in <tt>extensions</tt>.

For example, the SDKTools binary on Counter-Strike would be loaded from <tt>extensions/auto.1.ep1</tt>, but the GeoIP binary (which is not dependent) would be loaded from <tt>extensions</tt>.

=Removing SSE=
SourceMod binaries are built against SSE by default. SSE is an important set of optimizations, that, according to Valve's hardware survey, are supported on 99.6% percent of respondents' computers. If you are in this 0.4% which does not have SSE support, you should consider buying a newer processor. Only early Pentium 3-grade processors did not have SSE support (for example, the very early Durons), and it is likely your Source server will not perform adequately to support more than few players.

Nonetheless, SourceMod's binaries can all be recompiled to remove its SSE dependence.

==Linux==
Edit the Makefile of the binary you are trying to compile. Remove all instances of these flags. They can simply be erased, there is no need to replace them with anything.
*<tt>-msse</tt>
*<tt>-mfpmath=sse</tt>

Make sure to clean the build after changing the Makefile.

==Windows==
Load the project file into Visual Studio. Go to Project -> Properties. Expand "Configuration Properties," and then "C/C++" under it. Select "Code Generation." Change the setting "Enable Enhanced Instruction Set" to "Not Set."

'''Note:''' You must change this setting '''for each build configuration''' that you wish to use.

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

Building SourceMod

2009-08-11T21:51:14Z

Applecorc: Fixed page to match makefile

Compiling SourceMod is not difficult, but requires a number of prerequisites. This article details the requirements and steps to being able to build working SourceMod binaries. These directions may change any time and may be updated as SourceMod's build process improves.

'''Note:''' You cannot use MingW to build working SourceMod Windows binaries. It is not ABI compatible with Visual C++ which is what Valve uses for the Source engine. You can only use GCC to build Linux binaries.

=Requirements=

==Windows==
*Microsoft Visual C++ 2008 (Express or higher) is supported and used for official builds.
*Microsoft Visual C++ 2005 (Express or higher) is unsupported.
*Microsoft Visual C++ 2003 7.1 or higher may not build out-of-box, but can build compatible binaries.
*Microsoft Visual C++ 2003 7.0 or lower '''cannot''' be used.

If you are installing Visual C++ 2005 Express, it may not come with Microsoft's Platform SDK installed. If this is the case, you must manually install the Platform SDK. You can find directions on how to do this and test your setup [http://www.microsoft.com/express/2005/platformsdk/default.aspx here]. Visual C++ 2008 "streamlines" the Platform SDK installation according to Microsoft.

==Linux==
For Linux, SourceMod requires the GNU C/C++ Compiler (from GCC):
*Version 4.1 is used for official binaries and is guaranteed to build.
*Versions 3.4 through 4.2 are guaranteed to be binary (ABI) compatible, although SourceMod may not necessarily build out-of-box against them.
*Any GCC version below 3.4 '''cannot''' be used.

==CPU==
SourceMod is strictly a 32-bit x86 (IA32) product. You should not try to force a compiler to build 64-bit binaries of SourceMod.

Your CPU and its compiler must support SSE in order to build SourceMod. To build without needing or having a dependency against SSE, please see the [[Compiling SourceMod#Removing SSE|Removing SSE]] section near the bottom.

Approximate compiling times for SourceMod's Core are roughly:
*Windows, Core 2 Quad E6600: 30 seconds (using /MP)
*Windows, Core 2 Duo E6600: 75 seconds
*Windows, Centrino 1.8GHz: 5 minutes
*Linux, Core 2 Duo E6600: <= 1 minute
*Linux, P3 Dual 500MHz: >= 7 minutes

=Setup=
This section describes how to set up your computer for compiling.

==Getting the Files==
This section describes which files you must obtain and how to obtain them. Do not worry about where to place them yet -- that will be discussed on a per-platform basis. You can download the files anywhere you'd like.

The recommended method of getting the required files is via [http://subversion.tigris.org/ Subversion]. We have our own [[Subversion Tutorial]] if you prefer that method. Although you do not need both HL2SDK versions (unless you wish to build binaries against both), you do need both Metamod:Source versions. Extensions don't necessarily require Metamod:Source (or even the Source Engine) but its template library is used extensively in SourceMod.

*SourceMod. For full download options, see the [http://www.sourcemod.net/downloads.php SourceMod Downloads] page. Obviously, you must download the source code and not a binary package.
*HL2SDK Original. As of this writing (Sep 2008) this engine is used for most Source games, except for TF2, GMod10, and DoD:S. Repository: [http://hg.alliedmods.net/hl2sdk hl2sdk]
*HL2SDK OrangeBox. As of this writing (Sep 2008) this engine is used TF2, GMod10, and DoD:S. Repository: [http://hg.alliedmods.net/hl2sdk-ob hl2sdk-ob]
*Metamod:Source Source Code. Visit [http://www.metamodsource.net/?go=downloads Metamod:Source downloads]. Right now SourceMod builds against Metamod:Source 1.7.

'''Note''' that when we refer to "Metamod:Source" in this article, we are referring to its source code tree, not a binary package.

If you intend to compile the MySQL extension, you must also download MySQL 5.0. You can use any version. For simplicity, here are the versions we use:
*Linux: We use the 5.0.45 binary from the "[http://dev.mysql.com/downloads/mysql/5.0.html#linux Linux (non RPM packages)]" for "Linux (x86)." You can also use [http://dev.mysql.com/get/Downloads/MySQL-5.0/mysql-5.0.45-linux-i686-glibc23.tar.gz/from/pick this direct link] (may not be valid in the future).
*Windows: Due to a MySQL build change we use 5.0.24a which is an older download. The file name was "mysql-5.0.24a-win32.zip," if you can't find it you can use this [http://www.bailopan.net/mysql-5.0.24a-win32.zip direct link] (may not be valid in the future).

You can remove all folders from the distribution except for the "lib" and "include" folders which comprise the MySQL SDK.

==Linux==
As of this writing, SourceMod's Makefiles are hardcoded to use a binary called "gcc-4.1" You can override this, for example:
<pre>make CPP=gcc</pre>

Otherwise, you can also just create a symlink:
<pre>sudo ln -s /usr/bin/gcc /usr/bin/gcc-4.1</pre>

Note that you must use <tt>gcc</tt> and not <tt>g++</tt>.

SourceMod's Makefiles have strict directory organizational rules. You must have a top-level folder. For this document, we'll assume it is called <tt>sourcemod</tt>, though it can be named anything. The layout of <tt>sourcemod</tt> must be:
*<tt>sourcemod</tt>/
**<tt>hl2sdk</tt> - symlink or folder containing the HL2SDK
**<tt>hl2sdk-ob</tt> - symlink or folder containing the HL2SDK for Orange Box/TF
**<tt>mmsource-1.7</tt> - symlink or folder containing any Metamod:Source version 1.7 or higher.
**<tt>sourcemod-central</tt> - folder containing SourceMod's source code tree. This can be named anything, as long as it's a valid SourceMod tree (like [http://hg.alliedmods.net/sourcemod-central sourcemod-central]). You can also use [http://hg.alliedmods.net/sourcemod-1.1 sourcemod-1.1].
**<tt>mysql-5.0</tt> - symlink or folder containing a MySQL 5.0 distribution

If you are using a 64-bit version of Linux, you may need to install extra packages to be able to compile SourceMod. On Debian-based distros, these are typically:
<pre>
#prerequisites
#apt-get install g++-4.1 gcc-4.1 make subversion
#apt-get instal libz libz-dev
#only needed if you want to use the build tool
#apt-get install mono mono-devel
#32-bit support
apt-get install ia32-libs
apt-get install lib32z1 lib32z1-dev
apt-get install libc6-dev-i386 libc6-i386
</pre>

==Windows==
On Windows we don't require a particular directory layout. Instead, environment variables are used. The directions below apply to Windows XP, and are assumed to be similar for other versions of Windows.
*Open the Control Panel (for example, via Start -> Settings).
*Open the System control. If you don't see it, you may need to switch to "Classic view" (either via the left-hand pane or by going to Tools -> Folder Options).
*Click the Advanced tab.
*Click the Environment Variables button.

You can add your environment variables to either your User settings or your System settings. Create a new variable for each item in the list below. The item names are in <tt>fixed-width font</tt> and their value descriptions follow.
*<tt>MMSOURCE17</tt> - Path to Metamod:Source 1.7+
*<tt>HL2SDK</tt> - Path to HL2SDK Ep1/Original
*<tt>HL2SDKOB</tt> - Path to HL2SDK Ep2/OrangeBox

=Building=
SourceMod has two types of binaries: those with an engine/MM:S dependence, and those without ("normal" binaries). Normal binaries have two modes:
*<tt>Release</tt> - Optimized binary for release.
*<tt>Debug</tt> - Unoptimized binary with debugging checks.

Engine/MM:S dependent binaries have three build modes, each paired with either Release or Debug, meaning there are six build options total. They are:
*<tt>Original</tt> - Building against MM:S 1.4 API with HL2SDK
*<tt>Episode2</tt> - Building against MM:S 1.6 API with HL2SDK-OB or higher

==Linux==
For both Normal and Engine/MM:S dependent binaries, the object files and the final binary are placed in a folder called <tt>Release</tt> or <tt>Debug</tt> (in the same level as the Makefile) depending on which building mechanism you chose.

'''Note:''' Our Makefiles are not set up to detect changes in header files. If you change a header file, you must clean your build.

===Normal Binaries===
For normal binaries, you can build simply with:

<pre>make</pre>

You can clean stale object files with:
<pre>make clean</pre>

Or build debug builds with:
<pre>make DEBUG=true</pre>

===Dependent Binaries===
Binaries that have an Engine or MM:S dependency require one extra parameter, <tt>ENGINE</tt>. It must be either <tt>orangebox</tt> or <tt>original</tt>. For example, to build a TF-compatible binary in debug mode:

<pre>make ENGINE=orangebox DEBUG=true</pre>

Dependent binaries are dropped into one of the following folders:
*Debug.original
*Debug.orangebox
*Release.original
*Release.orangebox

==Windows==
Windows project files end with <tt>.vcproj</tt> and are found in an <tt>msvc8</tt> folder that resides inside each binary's main source folder. For example, Core is located in <tt>core/msvc8/sourcemod_mm.vcproj</tt>.

Once the file is opened, you can select which build to use by going to Build -> Configuration Manager. Normal binaries have simply "Debug" and "Release." Dependent binaries have the following builds:
*Debug - Old Metamod
*Debug - Episode 2
*Release - Old Metamod
*Release - Episode 2

'''Note''' that dependent binaries will have plain "Debug" and "Release" builds. These should not be used as they are not configured.

Once you have selected a configuration, you can compile by going to Build -> Build Solution. The binaries and object files will be written to a folder inside <tt>msvc8</tt> named after the full configuration name. For example, using "Debug - Old Metamod" with the "sdktools" extension will result in the binary: <tt>extensions/sdktools/msvc8/Debug - Old Metamod/sdktools.ext.dll</tt>

'''Note:''' Visual Studio detects changes to header files intelligently. It is usually not necessary to rebuild a solution.

=Binary Organization=
Although SourceMod has a somewhat unified building mechanism, each of the binaries has a different purpose. They can be separated into the following classes:

*Core-Related: Binaries which are required or loaded intrinsically by Core.
*Extensions: Binaries which are loaded via the extension mechanism.
*External: Binaries which are standalone or unrelated to SourceMod's live operation (for example, the compiler).

This article is only concerned with the first two types.

==Core-Related Binaries==
Binaries related to Core are spread throughout the source code tree. They are always placed in <tt>sourcemod/bin</tt> for packaging. The projects files related to Core are:

*<tt>loader</tt> - This is a very small wrapper binary responsible for detecting the MM:S version and game engine, and deciding which SourceMod version to load. The output binary is <tt>sourcemod_mm_i486.so</tt> or <tt>sourcemod_mm.dll</tt>.
*<tt>core</tt> - This is Core itself, and is a dependent binary. It has three outputs:
**Original: <tt>sourcemod.1.ep1.so</tt>/<tt>sourcemod.1.ep1.dll</tt>
**Episode 1: <tt>sourcemod.1.ep1.so</tt>/<tt>sourcemod.2.ep1.dll</tt> (unsupported, not packaged)
**Episode 2: <tt>sourcemod.1.ep1.so</tt>/<tt>sourcemod.2.ep2.dll</tt>
*<tt>sourcepawn/jit/x86</tt> - This is the SourcePawn JIT for generating IA32/x86 instructions from <tt>.smx</tt> files. Currently the source code for this is not made available. It is built as <tt>sourcepawn.jit.x86.so</tt>/<tt>sourcepawn.jit.x86.dll</tt>.

It is technically not necessary to use the loader. It is provided as a convenience so users do not have to perform extra steps while installing SourceMod. However, it is highly recommend that you do use it in order to maintain similarity with the default SourceMod package.

==Extensions==
Extensions are found in the <tt>extensions</tt> folder of the source tree. SDKTools, Cstrike, and the upcoming TF extension are engine/MM:S dependent (and the rest are generally not).

Extensions always are named <tt>name.ext.so</tt> or <tt>name.ext.dll</tt> where <tt>name</tt> is a unique identifier. This is true even of dependent binaries.

When loading extensions, SourceMod looks in two separate folders. First, it checks the ''dependent extension folder'', which is <tt>extensions/auto.x.y</tt> where <tt>x</tt> is the MM:S version (1 for 1.4, 2 for 1.6) and <tt>y</tt> is the Engine version (1 for Original/Ep1, 2 for Ep2/OrangeBox). If no matching extension is found there, it looks in <tt>extensions</tt>.

For example, the SDKTools binary on Counter-Strike would be loaded from <tt>extensions/auto.1.ep1</tt>, but the GeoIP binary (which is not dependent) would be loaded from <tt>extensions</tt>.

=Removing SSE=
SourceMod binaries are built against SSE by default. SSE is an important set of optimizations, that, according to Valve's hardware survey, are supported on 99.6% percent of respondents' computers. If you are in this 0.4% which does not have SSE support, you should consider buying a newer processor. Only early Pentium 3-grade processors did not have SSE support (for example, the very early Durons), and it is likely your Source server will not perform adequately to support more than few players.

Nonetheless, SourceMod's binaries can all be recompiled to remove its SSE dependence.

==Linux==
Edit the Makefile of the binary you are trying to compile. Remove all instances of these flags. They can simply be erased, there is no need to replace them with anything.
*<tt>-msse</tt>
*<tt>-mfpmath=sse</tt>

Make sure to clean the build after changing the Makefile.

==Windows==
Load the project file into Visual Studio. Go to Project -> Properties. Expand "Configuration Properties," and then "C/C++" under it. Select "Code Generation." Change the setting "Enable Enhanced Instruction Set" to "Not Set."

'''Note:''' You must change this setting '''for each build configuration''' that you wish to use.

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