Client Preferences API (SourceMod)

The Client Preferences extension is bundled with SourceMod 1.1 and higher. It lets you associate key/value pairs with clients who connect to servers. This information persists across client connections, and therefore across map changes and server restarts, and even servers.

Note:For information to be synchronized across multiple servers, the extension must be configured on each server to access settings on a shared database (most commonly running MySQL). By default, settings are saved in a standalone SQLite database unique to each server.

Cookies

The basic unit of information is a "cookie". Cookies are unique keys registered by plugins, similar to ConVars. Cookie names should always be reasonably descriptive to avoid clashes.

Cookies are registered using RegClientCookie, usually in OnPluginStart. Each cookie has a permission associated with it. A "public" cookie means a client can see and change the value they have for this cookie. A "protected" cookie means the client can only read it. A "private" cookie is completely hidden from the user.

The value of a cookie for a given client can be set using SetClientCookie, or retrieved using GetClientCookie. The default value of a Cookie is an empty string. Cookies are always stored as Strings, so if you want to store or retrieve cells/bools/Handles or Floats, you will need to convert them. This can be done using the StringToInt, IntToString, StringToFloat, and FloatToString functions.

Asynchronicity

When a client connects, their cookie information is retrieved asynchronously. This means their data is not immediately available.

Use the AreClientCookiesCached native to detect whether a user's cookies are available yet. If not, you will have to wait until OnClientCookiesCached is called for that client. There is no guarantee that these will succeed. For example, a player could connect and leave before a MySQL server responds.

Cookie Menus

The original intent of Client Preferences was to abstract preferences. For example, you might want to keep track whether a client wants to see a particular message or not.

To assist this type of code, there is a unified "cookie menu" system. The API is similar to TopMenus with the benefit that prefab menu formats are available. Prefab cookie menus are created using SetCookiePrefabMenu. The available prefabs are "Yes / No" and "On / Off". Fully custom menus can be created via SetCookieMenuItem.

Client Commands

The sm_cookies command allows users to view and set cookies. The sm_settings command displays the cookie menu.

Example

#include <clientprefs>
 
Handle g_hMyCookie;
 
public void OnPluginStart()
{
	g_hMyCookie = RegClientCookie("myplugin_mycookie", "MyPlugin MyCookie", CookieAccess_Protected);
}
 
public void SomeActionThatUsesCookie(int client)
{
	if (AreClientCookiesCached(client))
	{
		// Get cookie and add 1 to it
		char sCookieValue[12];
		GetClientCookie(client, g_hMyCookie, sCookieValue, sizeof(sCookieValue));
		int cookieValue = StringToInt(sCookieValue);
		cookieValue++;
 
		IntToString(cookieValue, sCookieValue, sizeof(sCookieValue));
 
		SetClientCookie(client, g_hMyCookie, sCookieValue);
	}
}