Difference between revisions of "Client Preferences API (SourceMod)"
m (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...) |
m (Switch headers to level 2, as per WikiMedia standard (first header is for page title)) |
||
| 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. | ||
| − | =Cookies= | + | ==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. | ||
| Line 8: | Line 8: | ||
The value of a cookie for a given client can be set using SetClientCookie, or retrieved using GetClientCookie. | The value of a cookie for a given client can be set using SetClientCookie, or retrieved using GetClientCookie. | ||
| − | =Asynchronicity= | + | ==Asynchronicity== |
When a client connects, their cookie information is retrieved asynchronously. This means their data is not immediately available. | 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 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= | + | ==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. | 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. | 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= | + | ==Client Commands== |
The <tt>sm_cookies</tt> command allows users to view and set cookies. | The <tt>sm_cookies</tt> command allows users to view and set cookies. | ||
The <tt>sm_settings</tt> command displays the cookie menu. | The <tt>sm_settings</tt> command displays the cookie menu. | ||
Revision as of 09:09, 18 October 2012
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 sm_cookies command allows users to view and set cookies. The sm_settings command displays the cookie menu.
