From 2d75efbbf73dbba847a28fcc8ab989f4741bba75 Mon Sep 17 00:00:00 2001 From: Mark Mandel Date: Fri, 5 Jan 2024 15:30:57 +1100 Subject: [PATCH] Counts and Lists: Improvements to SDK docs Much like the player tracking SDK documentation, I wanted to be explicit in the SDK documentation for Counts and Lists where data was being stored, and where default values where coming from with links back to the generated API reference - so made some improvements to help facilitate that. This does still need a Counters and Lists landing page to reference (this is my next task) as well, but wanted to get this done while I was thinking about it. Work on #2716 --- .../en/docs/Guides/Client SDKs/_index.md | 58 ++++++++++++------- 1 file changed, 36 insertions(+), 22 deletions(-) diff --git a/site/content/en/docs/Guides/Client SDKs/_index.md b/site/content/en/docs/Guides/Client SDKs/_index.md index a077e3ab1e..2a7dc85b72 100644 --- a/site/content/en/docs/Guides/Client SDKs/_index.md +++ b/site/content/en/docs/Guides/Client SDKs/_index.md @@ -230,11 +230,17 @@ observable through the Kubernetes API. ### Counters And Lists -{{< alpha title="Counters And Lists" gate="CountersAndLists" >}} +{{< alpha title="Counters And Lists" gate="CountsAndLists" >}} The `Counters` and `Lists` features in the SDK offer a flexible configuration for tracking various entities like players, rooms, and sessions. +Declared keys and default values for Counters and Lists are specified in +[`GameServer.Spec.Counters` and `GameServer.Spec.Lists`][gameserverspec] respectively. + +Modified Counter and List values and capacities will be updated +in [`GameServer.Status.Counters` and `GameServer.Status.Lists`][gameserverstatus] respectively. + {{< alert title="Note" color="info">}} The SDK batches mutation operations every 1 second for performance reasons. However, changes made and subsequently retrieved through the SDK will be atomically accurate through the SDK, as those values are tracked within the @@ -250,73 +256,81 @@ modified concurrently through the SDK and Allocation/Kubernetes API. #### Counters -All functions will return an error if the specified `key` is not predefined in the `GameServer.spec.counters` resource -configuration. +All functions will return an error if the specified `key` is not predefined in the +[`GameServer.Spec.Counters`][gameserverspec] resource configuration. ##### Alpha().GetCounterCount(key) -This function retrieves the current count for a counter in the game server. +This function retrieves the most up-to-date count value for a counter in the game server for a given key. ##### Alpha().SetCounterCount(key, amount) -This function sets the count to a given value. This operation overwrites any previous values and the new value cannot -exceed the Counter's capacity. +This function sets the value of [`GameServer.Status.Counts[key].Count`][gameserverstatus] for the given key to the +passed in amount. This operation overwrites any previous values and the new value cannot exceed the Counter's capacity. ##### Alpha().IncrementCounter(key, amount) -This function increments the count of a counter by a given non-negative value amount. The function returns an -error if the Counter is already at capacity (at time of operation), indicating no increment will occur. +This function increments [`GameServer.Status.Counts[key].Count`][gameserverstatus] for the given key by the passed in +non-negative amount. The function returns an error if the Counter is already at capacity (at time of operation), +indicating no increment will occur. ##### Alpha().DecrementCounter(key, amount) -This function decreases the count of a counter by a given non-negative amount. It returns an error if the -Counter's count is already at zero. +This function decreases [`GameServer.Status.Counts[key].Count`][gameserverstatus] for the given key by the passed in +non-negative amount. It returns an error if the Counter's count is already at zero. ##### Alpha().SetCounterCapacity(key, amount) -This function sets the maximum capacity for a counter. A capacity value of 0 indicates no capacity limit. +This function sets the maximum [`GameServer.Status.Counts[key].Capacity`][gameserverstatus] for the given key by the +passed in non-negative amount. A capacity value of 0 indicates no capacity limit. ##### Alpha().GetCounterCapacity(key) -This function retrieves the maximum capacity of a counter. +This function retrieves the most up-to-date maximum capacity of a Counter for the given key. #### Lists -All functions will return an error if the specified `key` is not predefined in the `GameServer.spec.lists` resource -configuration. +All functions will return an error if the specified `key` is not predefined in the +[`GameServer.Spec.Lists`][gameserverspec] resource configuration. ##### Alpha().AppendListValue(key, value) -This function appends the specified string value to a List's values. +This function appends the specified string value to the List +in [`GameServer.Status.Lists[key].Values`][gameserverstatus]. An error is returned if the string already exists in the list or if the list is at capacity. ##### Alpha().DeleteListValue(key, value) -This function removes the specific string value string from a List's values. +This function removes the specified string value from the List +in [`GameServer.Status.Lists[key].Values`][gameserverstatus]. An error is returned if the string does not exist in the list. ##### Alpha().SetListCapacity(key, amount) -This function sets the capacity for a specified List with the capacity value required to be -between 0 and 1000. +This function sets the maximum capacity for the List at [`GameServer.Status.Lists[key].Capacity`][gameserverstatus]. + +The capacity value is required to be between 0 and 1000. ##### Alpha().GetListCapacity(key) -This function retrieves the capacity of a specified list. +This function retrieves the most up-to-date capacity of a List for a given key. ##### Alpha().ListContains(key, value) -This function returns a boolean value on if a specific string value exists in a list's values. +This function returns the most up-to-date result of if a specific string value exists in a List for a given key. ##### Alpha().GetListLength(key) -This function retrieves the number of items (length) in a specified List. +This function retrieves the most up-to-date number of items (length) in a List for a given key. ##### Alpha().GetListValues(key) -This function returns an array of all the string values from a specified list. +This function returns the most up-to-date array of string values from a List for a given key. + +[gameserverspec]: {{< ref "/docs/Reference/agones_crd_api_reference.html#agones.dev/v1.GameServerSpec" >}} +[gameserverstatus]: {{< ref "/docs/Reference/agones_crd_api_reference.html#agones.dev/v1.GameServerStatus" >}} ### Player Tracking