Client Preferences API (SourceMod) - Revision history

Nosoop: Add note for multiple server handling

2024-01-01T00:33:07Z

Add note for multiple server handling

Sarrus: Added default value of a cookie

2020-08-21T23:19:34Z

Added default value of a cookie

Fakuivan: /* Example */ changed sCookieValue array to be 12 items long instead of 11 to accomodate for a minus sign

2016-11-27T23:01:00Z

‎Example: changed sCookieValue array to be 12 items long instead of 11 to accomodate for a minus sign

Fakuivan: /* Example */ updated to 1.7 sourcepawn declarations

2016-11-27T22:49:03Z

‎Example: updated to 1.7 sourcepawn declarations

Fakuivan: AreClientCookiesCached is referenced as a netive. Corrected some minor punctuation issues.

2016-11-27T22:44:27Z

AreClientCookiesCached is referenced as a netive. Corrected some minor punctuation issues.

Powerlord: Added an example

2012-10-18T15:40:42Z

Added an example

Powerlord: Switch headers to level 2, as per WikiMedia standard (first header is for page title)

2012-10-18T15:09:09Z

Switch headers to level 2, as per WikiMedia standard (first header is for page title)

BAILOPAN: New page: 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 cli...

2008-12-29T01:29:01Z

New page: 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 cli...

New page

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

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

Use the AreClientCookiesCached forward 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 <tt>sm_cookies</tt> command allows users to view and set cookies.
The <tt>sm_settings</tt> command displays the cookie menu.

[[Category:SourceMod Development]]

← Older revision		Revision as of 00:33, 1 January 2024
Line 1:		Line 1:
	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.		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==		==Cookies==

@@ Line 6: / Line 6: @@
 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.
+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==

@@ Line 37: / Line 37: @@
+	{
 		// Get cookie and add 1 to it
-		char sCookieValue[11];
+		char sCookieValue[12];
 		GetClientCookie(client, g_hMyCookie, sCookieValue, sizeof(sCookieValue));
 		int cookieValue = StringToInt(sCookieValue);

@@ Line 25: / Line 25: @@
 <pawn>#include <clientprefs>
-new Handle:g_hMyCookie;
+Handle g_hMyCookie;
-public OnPluginStart()
+public void OnPluginStart()
+{
 	g_hMyCookie = RegClientCookie("myplugin_mycookie", "MyPlugin MyCookie", CookieAccess_Protected);
+}
-public SomeActionThatUsesCookie(client)
+public void SomeActionThatUsesCookie(int client)
+{
 	if (AreClientCookiesCached(client))
+	{
 		// Get cookie and add 1 to it
-		decl String:sCookieValue[11];
+		char sCookieValue[11];
 		GetClientCookie(client, g_hMyCookie, sCookieValue, sizeof(sCookieValue));
-		new cookieValue = StringToInt(sCookieValue);
+		int cookieValue = StringToInt(sCookieValue);
 		cookieValue++;

@@ Line 2: / Line 2: @@
 ==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.
+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.
@@ Line 11: / Line 11: @@
 When a client connects, their cookie information is retrieved asynchronously.  This means their data is not immediately available.
-Use the AreClientCookiesCached forward 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.
+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==