Shop, Wallet & Inventory Control
A wallet holds a user’s balance of the currencies (such as coins and diamonds) used within a game. An in-game shop is a facility that allows users to buy items, or bundles of items, with their game currency. For example, within a game, users might be able to buy a sword with 100 coins. Once bought, items are added to a user’s personal inventory.
An extended example of a game that makes use of these facilities is available at the location https://github.com/spilgames/tappy_plane_unity.
Understanding the Object Structures
This section describes the structure of the objects used within the Spil Games SDK to manage wallet, shop, and inventory functionality.
The requirements for the items shown in Table 5 must be defined by the Game’s producer. Once finalized, the Spil Games Account Manager will coordinate with Spil Games LiveOps to have them set up and managed within SLOT. Note that changes to any of these objects can only be made via SLOT, and not the Spil Games SDK.
Table 5: SLOT-Managed Objects
|Currencies||The currencies used in the game. For example, coins and diamonds. Each currency has an ID, a name, and a type (0 = Premium and 1 = Non-Premium).|
|Items||The items used in the game. For example, a sword. Each Item has an ID, a name, and a type (0 = Consumable, 1 = Booster, and 2 = Permanent). Images, including a display name and a description, can also be defined for items. Also item properties can be added to an item.|
|Unique Items||Same as Items but they are non-stackable. A unique id is assigned to each Unique Item as well as it having Unique Properties that the game can modify.|
|Gacha||The gacha items used in the game. This collection contains a list of possible items that the user can get when trying to open the gacha each having it’s own weight. It acts in the same way as an item.|
|Bundles||The bundles present in the game. A bundle is a collection of items. Each bundle has an ID, a name, a list of the items that will be gained by the player when they buy the bundle, and a list of one or more prices that relate to the currencies required for users to buy it. Imagines, including a display and a description, can also be defined for bundles.|
|Shop||The tabs that the define the shop layout. Each tab contains a name, a position, and a list of entries. Each entry has a label that is displayed in the shop, a position, and one of more bundle IDs.|
|Promotions||The promotions associated with the shop. Each promotion contains one or more bundle IDs which points to the received bundles, an amount value which represents the number of bundles in the promotion, an updated prices list, a discount label, and a start and end date. Items and bundles are described above.|
The objects shown in Table 6 are managed by the developer through the Spil Games SDK. Note that, in special cases, Spil Games Customer Support can also implement changes to a user’s wallet.
Table 6: SDK-Managed Objects.
|Wallet||Contains information about the user’s balance. It contains a list of currencies (that match the currencies defined in Table 1), a current balance, a delta, the game version being used, and a logic field which is either CLIENT or SERVER (currently, only CLIENT logic is fully implemented).|
|Inventory||Contains information about the current Items possessed by the user. It has the same structure as the Wallet object.|
Resetting Player Data
The Spil Games SDK provides the functionality to individually reset the player’s wallet or inventory. They are reset to the new player’s state. Alternatively, they can both be reset simultaneously. Use the following code:
Note that a user’s wallet information will be reset both locally (on the user’s device) and within SLOT.
Image Loading and Processing Support
The item and bundle objects defined for a game (see Table 5) can also contain images to be displayed inside your game. To download and display these images, use the following code:
This page describes how the Spil SDK handles a users wallet an in-game shop and the user’s inventory.
The wallet feature is holding a user’s virtual balance of a particular currency. E.g. the user has 100 coins in his wallet. A wallet can contain multiple currencies, e.g. coins and diamonds.
A user can buy items or bundles (a pack of multiple items) with his virtual currency. Let’s say a user can buy a sword with 100 coins.
When a user bought an item in the in-game shop it will be added to his personal inventory.
Important note: We created a full example game using all these features. Please see:<href=”https://github.com/spilgames/tappy_plane_unity”>https://github.com/spilgames/tappy_plane_unity
Before talking about the actual calls for these features it’s good to know the structure of the objects that the Spil SDK uses to manage these features:
- Spil Game Data
- Spil Player Data
Spil Game Data
The Spil Game Data contains information about the game. Like which currencies, Items, Bundles, Shop and Shop Promotions a game might have. See below the details:
- Currencies – this list contains all the currencies present in the game and defined in the Spil SLOT interface; each Currency of this list has an id, a name and a type (0 = premium and 1 = non-premium)
- Items – this list contains all the items present in the game and defined in the Spil SLOT interface; this includes the Gacha Items; each Item of this list has an id, a name and a type (0 = Consumable, 1 = Booster and 2 = Permanent)
- Bundles – this list contains all the bundles present in the game and defined in the Spil SLOT interface; each Bundle contains an id, a name, a list of one or more Items that will be gained by the player when he buys the bundle and a list of one or more prices that relate to the Currencies.
- Shop – this object contains a configuration of the shop as defined in SLOT interface; the object contains a list of Tabs that the define the shop layout; each Tab contains a name, a position and a list of Entries; each Entry in the list has a label that would be displayed in the shop, a position and a Bundle id which points to the received Bundles
- Promotions – this list contains all the promotions that would be associated with the Shop and configured in the SLOT interface; each Promotion contains a Bundle id which would point to the received Bundles, an amount value which would represent how many amounts of the bundle will be in the promotion, an updated prices list, a discount label and a start and end date
Spil Player Data
A Player Data contains the information related to what the user owns, the user’s Wallet and Inventory. See below the details:
- Wallet – this object contains the information regarding the user’s balance; the Wallet contains a list of Currencies that match the Currencies defined in the Spil Game Data with the addition of having a current balance and a delta, an offset which informs the Spil server which version of the wallet the game is currently having and a logic field which could either be CLIENT or SERVER (for now CLIENT logic is fully implemented)
- Inventory – similar object to the Wallet except it holds information about the current Items that the user have
Step 1) Default values
If there is no network connection, then the SDK will use the latest known defaults.
In exceptional cases, people will open the app for the first time and don’t have an Internet connection. For this specific case we need to add two defaults JSON files in the assets/streaming assets folder of the project:
Add a file named ‘defaultGameData.json‘ in the assets/streaming assets folder of your project.
Here is an example of a simple example file:
Add a file named ‘defaultPlayerData.json‘ in the assets/streaming assets folder of your project.
Here is an example of a simple example file:
Step 2) Default values
The Spil Unity classes “SpilGameDataHelper.cs” and “PlayerDataHelper.cs” contain all methods for the wallet, in-game shop and inventory features.
These classes are instantiated on “Awake ()” in the “Spil.cs” file and automatically retrieve the data from the Spil SDK, so you can start using the methods immediately.
See below code snippets to use the wallet, in-game shop and inventory features:
The SDK also provides the functionality to reset the player’s data, or just specifically the player’s Wallet and Inventory.
In order to reset the Wallet data use the following code:
In order to reset the Inventory data use the following code:
In order to reset the whole Player data use the following code:
Item and Bundles Image Processing and Loading
The Items and Bundles objects provided by the SDK can also contain images that can be displayed inside your game.
In order to download and display these images use the following information: