AlliedModders Wiki - User contributions [en]

Admin Menu (SourceMod Scripting)

2018-05-01T19:08:26Z

ThatKidWhoGames: Updated the syntax

The admin menu is a menu available to all in-game administrators. It is a simple, one-level, category-based menu with heavy focus on consistency. The menu is simply a <tt>TopMenu</tt>, from the TopMenus extension, and is provided by <tt>adminmenu.sp</tt>.

The menu itself has no items unless external plugins provide them. Thus, it is possible (and recommended) for third party developers to extend the menu by attaching their own functionality to it. This requires a bit of patience, but this article documents most of the steps necessary.

=Menu Organization=
The menu is organized into ''categories'' and ''items''. Categories are top-level selections on the menu. Items are selectable entries inside categories. There are two important rules:
*There is no nesting. Categories cannot have sub-categories.
*Only categories can exist at the top level (i.e. items must have a parent category).

All entries on the menu, be they categories or items, are called ''top menu objects'', and each must have a unique name. For simplicity, the default admin menu entries use their respective command names as unique names, however this style is not required or enforced.

Unique names are used to identify items for sorting. For more information, see [[Admin Menu Configuration (SourceMod)|Admin Menu Configuration]].

=Interfacing to the Admin Menu=
The admin menu plugin can be loaded or unloaded at any time, and accounting for this in your code is important. Generally, you must account for the following cases:
*The admin menu is unloaded while you are interfaced to it.
*The admin menu is loaded while your plugin is already loaded.
*The admin menu is loaded before your plugin is loaded.

You do not need to remove menu items; they are removed automatically when your plugin is unloaded, and temporarily removed while your plugin is paused.

Example code is below:
<pawn>
#include <sourcemod>

/* Make the admin menu plugin optional */
#undef REQUIRE_PLUGIN
#include <adminmenu>

/* Keep track of the top menu */
TopMenu hAdminMenu = null;

public void OnPluginStart()
{
/* See if the menu plugin is already ready */
TopMenu topmenu;
if (LibraryExists("adminmenu") && ((topmenu = GetAdminTopMenu()) != null))
{
/* If so, manually fire the callback */
OnAdminMenuReady(topmenu);
}
}

public void OnLibraryRemoved(const char[] name)
{
if (StrEqual(name, "adminmenu", false))
{
hAdminMenu = null;
}
}

public void OnAdminMenuReady(TopMenu topmenu)
{
/* Try to add the category first, if we want to add one.
Leave this out, if you don't add a new category. */
if (obj_dmcommands == INVALID_TOPMENUOBJECT)
{
OnAdminMenuCreated(topmenu);
}

/* Block us from being called twice */
if (topmenu == hAdminMenu)
{
return;
}

hAdminMenu = topmenu;

/* :TODO: Add everything to the menu! */
}</pawn>

=Top Menu Objects=
Top Menu Objects are entries, either categories or items, on the admin menu (or any top menu). Each has the following properties:
*<tt>ID</tt> (OUTPUT): The ID of the object in memory.
*<tt>Name</tt> (INPUT): The unique name of the object.
*<tt>Type</tt> (INPUT): Either a category or an item.
*<tt>Handler</tt> (INPUT): The callback function.
*<tt>Parent</tt> (INPUT): Empty for categories, or a category object ID for an item.
*<tt>Override</tt> (INPUT): The name of the override associated with the command. For more information, see [[Overriding Command Access (SourceMod)|Overriding Command Access]]. Overrides don't need to be a command name.
*<tt>Flags</tt> (INPUT): Default admin flags that should be associated with the object if the override is not set.

The callback determines how the object is drawn on the menu. If no flags are specified, the item is usable by any admin. If an admin does not have access to an object (including an entire category), it will not be displayed.

=Adding Categories=
Adding categories is sometimes beneficial for larger plugins with many commands. A category object receives two TopMenuAction callbacks:
*<tt>TopMenuAction_DisplayOption</tt> - The category is being displayed.
*<tt>TopMenuAction_DisplayTitle</tt> - The category is being displayed as a title.

For example, let's create a category called "CS:S DM Commands".

<pawn>
TopMenuObject obj_dmcommands;

public void OnAdminMenuCreated(TopMenu topmenu)
{
/* Block us from being called twice */
if (topmenu == hAdminMenu && obj_dmcommands != INVALID_TOPMENUOBJECT)
{
return;
}

obj_dmcommands = AddToTopMenu(topmenu,
"CS:S DM Commands",
TopMenuObject_Category,
CategoryHandler,
INVALID_TOPMENUOBJECT);
}

public void CategoryHandler(TopMenu topmenu,
TopMenuAction action,
TopMenuObject object_id,
int param,
char[] buffer,
int maxlength)
{
if (action == TopMenuAction_DisplayTitle)
{
Format(buffer, maxlength, "CS:S DM Commands:");
}
else if (action == TopMenuAction_DisplayOption)
{
Format(buffer, maxlength, "CS:S DM Commands");
}
}</pawn>

Note that a callback can handle more than one category. If that is the desired functionality, you can use the <tt>TopMenuObject</tt> value to see which object is being drawn.

=Adding Items=
Items are different from categories in that their selection can be detected. They must have a parent category. The code below shows an example of finding an existing category and adding an item to it.

<pawn>
void AttachAdminMenu()
{
/* If the category is third party, it will have its own unique name. */
TopMenuObject player_commands = FindTopMenuCategory(hAdminMenu, ADMINMENU_PLAYERCOMMANDS);

if (player_commands == INVALID_TOPMENUOBJECT)
{
/* Error! */
return;
}

AddToTopMenu(hAdminMenu,
"sm_poke",
TopMenuObject_Item,
AdminMenu_Poke,
player_commands,
"sm_poke",
ADMFLAG_SLAY);
}

public void AdminMenu_Poke(TopMenu topmenu,
TopMenuAction action,
TopMenuObject object_id,
int param,
char[] buffer,
int maxlength)
{
if (action == TopMenuAction_DisplayOption)
{
Format(buffer, maxlength, "Poke");
}
else if (action == TopMenuAction_SelectOption)
{
/* Do something! client who selected item is in param */
}
}</pawn>

Note that a callback can handle more than one item. If that is the desired functionality, you can use the <tt>TopMenuObject</tt> value to see which object is being drawn.

=Returning to the Menu=
Sometimes it is desirable to re-display the admin menu to the client. This can be achievied via <tt>RedisplayAdminMenu</tt> in <tt>adminmenu.inc</tt>.

[[Category:SourceMod Scripting]]

Timers (SourceMod Scripting)

2018-05-01T13:58:17Z

ThatKidWhoGames: /* Data Packs */

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

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

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

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

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

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

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

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

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

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

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

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

return Plugin_Continue;
}</pawn>

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

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

<pawn>
Handle WelcomeTimers[MAXPLAYERS+1];

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[[Category:SourceMod Scripting]]

{{LanguageSwitch}}

Timers (SourceMod Scripting)

2018-05-01T13:58:07Z

ThatKidWhoGames: Nvm reverting changes, didn't read section properly that it is data timer

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

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

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

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

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

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

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

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

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

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

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

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

return Plugin_Continue;
}</pawn>

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

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

<pawn>
Handle WelcomeTimers[MAXPLAYERS+1];

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[[Category:SourceMod Scripting]]

{{LanguageSwitch}}

Timers (SourceMod Scripting)

2018-05-01T13:56:11Z

ThatKidWhoGames: /* Data Packs */

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

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

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

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

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

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

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

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

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

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

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

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

return Plugin_Continue;
}</pawn>

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

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

<pawn>
Handle WelcomeTimers[MAXPLAYERS+1];

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[[Category:SourceMod Scripting]]

{{LanguageSwitch}}

Timers (SourceMod Scripting)

2018-05-01T13:55:04Z

ThatKidWhoGames: Updated the timer callback with the DataPack method map and closed the handle.

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

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

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

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

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

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

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

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

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

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

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

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

return Plugin_Continue;
}</pawn>

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

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

<pawn>
Handle WelcomeTimers[MAXPLAYERS+1];

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[[Category:SourceMod Scripting]]

{{LanguageSwitch}}