Player balances
Use the SDK to manage player currency balances.
Read time 3 minutesLast updated 7 months ago
The namespace contains all the methods for fetching and updating a player's currency balances.
PlayerBalancesThese methods will return the balances for the currently signed in player from the Authentication SDK.
Note
All the methods in this namespace can throw an EconomyException.
GetBalancesAsync
Retrieve the currency balances for the current user. Takes an optional .
GetBalancesOptionsWhen getting balances, you can use the to set a limit on the number of balances to fetch (between 1 and 100 inclusive). This is to help with pagination. The default number is 20.
GetBalancesOptionsThe following sample code retrieves the first five balances for the current user, and then retrieves the next five, including those for currencies that have since been deleted from the configuration.
// Optional, defaults to 20GetBalancesOptions options = new GetBalancesOptions{ ItemsPerFetch = 5};GetBalancesResult getBalancesResult = await EconomyService.Instance.PlayerBalances.GetBalancesAsync(options);List<PlayerBalance> firstFiveBalances = getBalancesResult.Balances;// do something with your balancesif (getBalancesResult.HasNext) { getBalancesResult = await getBalancesResult.GetNextAsync(options.ItemsPerFetch); List<PlayerBalance> nextFiveBalances = getBalancesResult.Balances; // do something with your balances}
These methods return a . See GetBalancesResult.
GetBalancesResultGetBalancesOptions
The options object for a call. It has the following field:
GetBalancesAsync- : An int. Defaults to 20. Use this to set the maximum number of balances to fetch per call between 1 and 100 inclusive.
ItemsPerFetch
GetBalancesResult
A provides paginated access to the list of balances retrieved. It has the following fields:
GetBalancesResult- : A
Balanceswith the currently fetched balances.List<PlayerBalance>
It has the following methods:
- : This method asynchronously fetches more results. It has one optional parameter to limit the amount of results fetched (this can be between 1 and 100 inclusive, default is 20). It will return a new result, which contains both the original items and the newly fetched items in its
GetNextAsync(int itemsToFetch = 20)list.Balances
SetBalanceAsync
Sets the balance of the specified currency to the specified value.
This method optionally takes a object used to set the write lock. If provided, an exception is thrown unless the matches the received by a previous read, in order to provide optimistic concurrency. If not provided, the transaction proceeds regardless of any existing in the data.
SetBalancesOptionswriteLockwriteLockwriteLockThis method returns the current balance after the update has been applied, if the operation is successful.
string currencyID = "GOLD_BARS";int newAmount = 1000;string writeLock = "someLockValueFromPreviousRequest";SetBalanceOptions options = new SetBalanceOptions{ WriteLock = writeLock};PlayerBalance newBalance = await EconomyService.Instance.PlayerBalances.SetBalanceAsync(currencyID, newAmount);// ORPlayerBalance otherNewBalance = await EconomyService.Instance.PlayerBalances.SetBalanceAsync(currencyID, newAmount, options);
SetBalanceOptions
The options object for a call. It has the following field:
SetBalanceAsync- : A string. Defaults to
WriteLock. Use this to set a write lock for optimistic concurrency. See Write Lock.null
IncrementBalanceAsync
Increments the balance of the specified currency by the specified value.
This method optionally takes a object used to set the write lock. If provided, then an exception is thrown unless the matches the received by a previous read, in order to provide optimistic concurrency. If not provided, the transaction proceeds regardless of any existing in the data.
IncrementBalancesOptionswriteLockwriteLockwriteLockThis method returns the current balance after the update is applied, if the operation is successful.
string currencyID = "GOLD_BARS";int incrementAmount = 1000;string writeLock = "someLockValueFromPreviousRequest";IncrementBalanceOptions options = new IncrementBalanceOptions{ WriteLock = writeLock};PlayerBalance newBalance = await EconomyService.Instance.PlayerBalances.IncrementBalanceAsync(currencyID, newAmount);// ORPlayerBalance otherNewBalance = await EconomyService.Instance.PlayerBalances.IncrementBalanceAsync(currencyID, newAmount, options);
IncrementBalanceOptions
The options object for a call. It has the following field:
IncrementBalanceAsync- : A string. Defaults to
WriteLock. Use this to set a write lock for optimistic concurrency. See Write Lock.null
DecrementBalanceAsync
Decrements the balance of the specified currency by the specified value.
This method optionally takes a object used to set the write lock. If provided, then an exception is thrown unless the matches the received by a previous read, in order to provide optimistic concurrency. If not provided, the transaction proceeds regardless of any existing in the data.
DecrementBalanceOptionswriteLockwriteLockwriteLockThis method returns the current balance after the update is applied, if the operation is successful.
string currencyID = "GOLD_BARS";int decrementAmount = 1000;string writeLock = "someLockValueFromPreviousRequest";DecrementBalanceOptions options = new DecrementBalanceOptions{ WriteLock = writeLock};PlayerBalance newBalance = await EconomyService.Instance.PlayerBalances.DecrementBalanceAsync(currencyID, newAmount);// ORPlayerBalance otherNewBalance = await EconomyService.Instance.PlayerBalances.DecrementBalanceAsync(currencyID, newAmount, options);
DecrementBalanceOptions
The options object for a call. It has the following fields:
DecrementBalanceAsync- : A string. Defaults to
WriteLock. Use this to set a write lock for optimistic concurrency. See Write Lock.null
PlayerBalance
A player balance represents a single currency balance for a player. It has the following fields:
- : The ID of the currency this balance represents.
CurrencyId - : The integer amount of this currency the player has.
Balance - : The current
WriteLockstring.writeLock - : The date this balance was created. It is an EconomyDate object.
Created - : The date this balance was modified. It is an EconomyDate object.
Modified
It also has the following helper methods:
GetCurrencyDefinitionAsync
This is a convenience method to get the currency definition for the currency associated with this balance. It returns a CurrencyDefinition.
PlayerBalance myPlayerBalance = ... // Get a player balance from one of the above methodsCurrencyDefinition currencyDefForMyPlayerBalance = myPlayerBalance.GetCurrencyDefinitionAsync();
BalanceUpdated
This event can be subscribed to in order to be notified when the SDK updates the balance of a particular currency. The subscriber is passed the currency ID of the balance that was updated.
Note
This event is be called for SDK initiated actions (for example, updating player's balances, making purchases). It is not called for any updates from other devices / service side changes.
EconomyService.Instance.PlayerBalances.BalanceUpdated += currencyID => { Debug.Log($"The currency that was updated was {currencyID}");};