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.

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. 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>
 
new Handle:g_hMyCookie;
 
public OnPluginStart()
{
	g_hMyCookie = RegClientCookie("myplugin_mycookie", "MyPlugin MyCookie", CookieAccess_Protected);
}
 
public SomeActionThatUsesCookie(client)
{
	if (AreClientCookiesCached(client))
	{
		// Get cookie and add 1 to it
		decl String:sCookieValue[11];
		GetClientCookie(client, g_hMyCookie, sCookieValue, sizeof(sCookieValue));
		new cookieValue = StringToInt(sCookieValue);
		cookieValue++;
 
		IntToString(cookieValue, sCookieValue, sizeof(sCookieValue));
 
		SetClientCookie(client, g_hMyCookie, sCookieValue);
	}
}