AlliedModders Wiki - User contributions [en]

Menus Step By Step (SourceMod Scripting)

2017-10-23T10:26:55Z

NgBUCKWANGS:

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.GetInfo(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.

SourcePawn Basics - Customization through ConVars

2016-11-05T12:25:53Z

NgBUCKWANGS:

Prerequisite: This guide assumes you have read [[Introduction to SourcePawn]] and [[Introduction to SourceMod Plugins]].

Server owners like customization. Lots of customization. So, how do you add customization to your plugin? The simplest route is by adding ConVars.

== General Info ==

Console Variables (ConVars or CVars for short) are server settings that can be changed by server owners. Anything you put into your server's server.cfg file is a convar.

Just like the server itself, plugins can create their own convars. A convar is different from a regular variable in that it is visible outside your plugin.

== Creating your own ConVars ==

ConVars should always be created in OnPluginStart.

When you create your ConVars, they should name them consistently. A good naming practice is <tt>nameofplugin_settingname</tt> or <tt>nameofplugin_setting_name</tt>.

ConVars are created via the CreateConVar command. The order of arguments are:

; name : The convar name, preferably using the naming scheme above
; defaultValue : A string with the default value.
; description : A description of what this ConVar does for the find or listcvars commands
; flags : An | separate list of convar flags
; hasMin : A bool stating whether the min argument exists
; min : A Float with the minimum allowed value
; hasMax : A bool stating whether the max argument exists
; min : A Float with the maximum allowed value

=== Useful ConVar Flags ===

* <tt>FCVAR_NONE</tt> - The default, no flags set.
* <tt>FCVAR_PROTECTED</tt> - Used for passwords. Don't send this value to clients who ask for it, only send 1 if it's set or 0 if it isn't.
* <tt>FCVAR_SPONLY</tt> - Not changeable in multiplayer
* <tt>FCVAR_NOTIFY</tt> - Players are informed when this ConVar changes. ConVars marked with this attribute are also visible to tracking services.
* <tt>FCVAR_NEVER_AS_STRING</tt> - Don't try to print this out
* <tt>FCVAR_DONTRECORD</tt> - Not recorded in demo files. Also, not recorded in <tt>AutoExecConfig</tt> files.
* <tt>FCVAR_PLUGIN</tt> - Defined by a 3rd Party plugin. SourceMod probably adds this already even if you don't.

== Standard ConVars ==

There are a few standard ConVars that most plugins have.

The first is a version ConVar. Unlike most ConVars, you don't need to store the <tt>Handle</tt> of this one as you never need to read its value.

Normally, your version ConVar will look a little like this.

#define VERSION "1.0"

public OnPluginStart()
{
CreateConVar("test_version", VERSION, "Test Plugin version", FCVAR_NOTIFY|FCVAR_DONTRECORD|FCVAR_PLUGIN|FCVAR_SPONLY);
}

<tt>|FCVAR_PLUGIN|FCVAR_SPONLY</tt> is not strictly required here, but it is fairly common to see them set.

<tt>VERSION</tt> is defined here so that it can be used in the plugin's myinfo struct as well.

A second common ConVar is the enable ConVar.

new Handle:g_hEnabled;

public OnPluginStart()
{
g_hEnabled = CreateConVar("test_enable", "1", "Test Plugin Enable", FCVAR_NOTIFY|FCVAR_DONTRECORD, true, 0.0, true, 1.0);
}

Note that FCVAR_DONTRECORD is still present. This is a recommendation in case your plugin has an <tt>AutoExecConfig</tt> file so that your enable ConVar can be controlled by map configurations or server.cfg.

FCVAR_NOTIFY is here as well so that GameTracker and the like can tell if the plugin is enabled.

=== Loading ConVars from a file ===

SourceMod has a command <tt>AutoExecConfig</tt> to automatically read/create a ConVar configuration file. To use it, put this at the end of OnPluginStart after your CreateConVar lines:

AutoExecConfig(true, "nameofplugin");

which will create a file named <tt>cfg/sourcemod/nameofplugin.cfg</tt>

== Locating ConVars from the game or other plugins ==

Looking up plugins is an expensive operation and should be done just once if you can help it.

The best location to do this is in the <tt>OnAllPluginsLoaded</tt> callback.

For example, here is how to look up the mp_autoteambalance ConVar

new Handle:g_hAutoTeamBalance;

public OnAllPluginsLoaded()
{
g_hAutoTeamBalance = FindConVar("mp_autoteambalance");
}

== Reading and Setting ConVars ==

Both ConVars from your plugin and ConVars from the game or other plugins can be read the same way.

ConVars can be read as several different kinds of values: cell (int), bool, Float, or String.

Here is how you read a bool ConVar:

new bool:value = GetConVarBool(g_hAutoTeamBalance);

and to set the same ConVar:

SetConVarBool(g_hAutoTeamBalance, true);

Int and Floats work roughly the same way with <tt>GetConVarInt</tt> / <tt>GetConVarFloat</tt> / <tt>SetConVarInt</tt> / <tt>SetConVarFloat</tt>.

Strings work the same for setting, but reading a String ConVar works slightly differently:

decl String:value[64];
GetConVarString(myConVar, value, sizeof(value));

This pattern is common for functions that do String manipulations.

== Catching that a ConVar changed ==

In addition to just reading and changing ConVar values, you can also catch when a ConVar's value is changed.

This is done through a ConVarChange hook. ConVarChange hooks only fire when the value changes from one state to another. So, if a ConVar is already set to 1 and a config changes it to 1 (the same value), the ConVarChange hook will '''not''' fire.

You can add a ConVarChange hook like this:

new Handle:g_hEnabled;

public OnPluginStart()
{
g_hEnabled = CreateConVar("test_enable", "1", "Test Plugin Enable", FCVAR_NOTIFY|FCVAR_DONTRECORD, true, 0.0, true, 1.0);
HookConVarChange(g_hEnabled, ConVar_EnableChange);
}

public ConVar_EnableChange(Handle:convar, const String:oldValue[], const String:newValue[])
{
new enabled = GetConVarBool(g_hEnabled);

if (enabled)
{
// We were just enabled
}
else
{
// We were just disabled
}
}

Note that it's quicker to use <tt>GetConVarBool</tt>, Int, or Float instead of converting oldValue or newValue to the appropriate types.

There is also an <tt>UnhookConVarChange</tt>, but it is largely unnecessary as these hooks are automatically released when your plugin unloads.

'''Make sure you hook the ConVar in the same function you Create or Find it.''' It's also a good idea to check the return value of FindConVar before hooking it, as a game that doesn't support a ConVar will return <tt>INVALID_HANDLE</tt>

== Reading ConVars from server.cfg ASAP ==
On server first launch, ConVars in server.cfg are loaded later than OnPluginStart (e.g, see <strong>Q: Can I get cvar values in OnPluginStart?</strong> on this page http://www.sourcemod.net/devlog/?p=126). A working example of how to read from server.cfg ASAP but falling back to a default value in case it doesn't exist follows.

ConVar g_YourConVar;
new g_YourGlobalVar;

public OnPluginStart() {
g_YourConVar = CreateConVar("your_convar", "your_default_value");
g_YourGlobalVar = g_YourConVar.IntValue;
HookConVarChange(g_YourConVar, YourGlobalVarHook);
}

public YourGlobalVarHook(Handle:convar, const String:oldValue[], const String:newValue[]) {
g_YourGlobalVar = GetConVarInt(g_YourConVar);
PrintToServer("g_YourGlobalVar Has Changed: %d", g_YourGlobalVar);
}

[[Category:SourcePawn Basics]]