Virtual Currencies

The PlayFab Virtual Currencies Module is specifically designed to manage the application's virtual store and currency.

The features include purchases, consumables, redeemable coupons, virtual stores, item catalogs and very your own virtual currencies. 

The store list, catalog items, virtual currencies and transaction data are accessible through the PlayFab Console. 

The implementation of virtual stores in your applications will be easier with this addon.

 

Intstructions

1. The first step is to add the PlayFab API addon into the project.

2. Then, add the Authentication addon into the project.

3. Finally, add the Virtual Currencies addon into the project.

Features :

  • Advanced to simple purchases.

  • Consumables and redeem coupons.

  • Virtual Currencies.

  • Store Console and versioning.

  • Account synced and profiled.

  • Organized request and update feature.

Network Services :

  • Facebook

  • Google Plus

  • Game Center

  • Google Play

  • Facebook Instant Games

  • Steam

  • Xbox Live

  • Nintendo Switch

  • PS4

  • PlayFab

Actions, Conditions & Expressions

Actions

Virtual Currency :

  • Add User Currency - Increments the user's balance of the specified virtual currency by the stated amount.

    • Virtual Currency - Name of the virtual currency which is to be incremented.

    • Amount - Amount to be added to the user balance of the specified virtual currency.

    • Tag - The tag to differentiate requests.

  • Subtract User Currency - Decrements the user's balance of the specified virtual currency by the stated amount. A Negative Balance is possible.

    • Virtual Currency - Name of the virtual currency which is to be decremented.

    • Amount - Amount to be subtracted from the user balance of the specified virtual currency.

    • Tag - The tag to differentiate requests.

Item Management :

  • Get User Inventory - Retrieves the user's current inventory of virtual goods.

    • Tag - The tag to differentiate requests.​​

  • Consume Item - Consume uses of a consumable item. When all uses are consumed, it will be removed from the player's inventory.

    • Item Instance ID - Unique instance identifier of the item to be consumed.

    • Consume Count - Number of uses to consume from the item.

  • Purchase Item - Buys a single item with virtual currency.

    • Item ID - Unique identifier of the item to purchase.

    • Price - Price the client expects to pay for the item (in case a new catalog or store was uploaded, with new prices).

    • Virtual Currency - Virtual currency to use to purchase the item.

  • Advanced Purchase Item - Buys a single item with virtual currency. Using advanced features.

    • Item ID - Unique identifier of the item to purchase.

    • Price - Price the client expects to pay for the item (in case a new catalog or store was uploaded, with new prices).

    • Store ID - Store to buy this item through. If not set, prices default to those in the catalog.

    • Virtual Currency - Virtual currency to use to purchase the item.

    • Catalog - Catalog version for the items to be purchased (defaults to most recent version.

    • Catalog Version - Specific Catalog version for the items to be purchased.


Reward Management :

  • Redeem Coupon - Adds the virtual goods associated with the coupon to the user's inventory.

    • Coupon Code - Generated coupon code to redeem.

    • Tag - The tag to differentiate requests.​

  • Redeem Coupon by Version - Adds the virtual goods associated with the coupon to the user's inventory. With Specify the Catalog Version.

    • Coupon Code - Generated coupon code to redeem.

    • Catalog Version - Catalog version of the coupon.

    • Tag - The tag to differentiate requests.​

Conditions

Virtual Currency :

  • On Add User Currency - Triggers when the On Add User Virtual Currency Succeeded.

  • On Add User Currency Error - Triggers when the On Add User Virtual Currency Failed.

  • On Subtract User Currency - Triggers when the On Subtract User Virtual Currency Succeeded.

  • On Subtract User Currency Error - Triggers when the On Subtract User Virtual Currency Failed.

Get User Inventory :

  • On Get User Inventory - Triggers when the On Get User Inventory Succeeded.

  • On Get User Inventory Error - Triggers when the On Get User Inventory Failed.

  • For Each Inventory - Loops through the "Inventory List" if "On Get User Inventory" is successful.


Consume Item :

  • On Consume Success - Triggers when the On Consume Item Succeeded.

  • On Consume Error - Triggers when the On Consume Item Failed.


Purchase Item :

  • On Purchase Success - Triggers when the On Purchase Item Succeeded.

  • On Purchase Error - Triggers when the On Purchase Item Failed.


Redeem Coupon :

  • On Redeem Success - Triggers when the On Redeem Coupon Succeeded.

  • On Redeem Error - Triggers when the On Redeem Coupon Failed.

  • On Coupon Already Redeemed - Triggers when the Coupon Code is already redeemed.

  • On Coupon Code Not Found - Triggers when the Coupon Code is not found.

  • For Each Received - Loops through the "Granted Items List" if "On Redeem Coupon" is successful.

Expressions

Consume Item :

  • conItemInstanceID - Returns the "Item Instance ID". Unique instance identifier of the item with uses consumed.

  • conRemainingUses - Returns the "Remaining Uses". Number of uses remaining on the item.

Purchase Item :

  • purItemID - Returns the "Item ID". Unique identifier for the inventory item, as defined in the catalog.

  • purItemInstanceID - Returns the "Item Instance ID". Unique item identifier for this specific instance of the item.

  • purDate - Returns the "Purchase Date". Timestamp for when this instance was purchased.

  • purCatalogVersion - Returns the "Catalog Version". Catalog version for the inventory item, when this instance was created.

  • purDisplayName - Returns the "Display Name". CatalogItem.DisplayName at the time this item was purchased.

  • purCurrency - Returns the "Unit Currency". Currency type for the cost of the catalog item.

  • purPrice - Returns the "Unit Price". Cost of the catalog item in the given currency.


Get User Inventory :: Inventory :

  • curItemID - Returns the "Item ID". Unique identifier for the inventory item, as defined in the catalog.

    • Index - The Index to lookup from the Inventory. Collected from the latest "Get User Inventory".

  • curItemInstanceID - Returns the "Item Instance ID". Unique item identifier for this specific instance of the item.

    • Index - The Index to lookup from the Inventory. Collected from the latest "Get User Inventory".

  • curItemClass - Returns the "Item Class". Class name for the inventory item, as defined in the catalog.

    • Index - The Index to lookup from the Inventory. Collected from the latest "Get User Inventory".

  • curCatalogVersion - Returns the "Catalog Version" for the inventory item, when this instance was created.

    • Index - The Index to lookup from the Inventory. Collected from the latest "Get User Inventory".

  • curPrice - Returns the "Unit Price". Cost of the catalog item in the given currency.

    • Index - The Index to lookup from the Inventory. Collected from the latest "Get User Inventory".

  • curCurrency - Returns the "Unit Currency". Currency type for the cost of the catalog item.

    • Index - The Index to lookup from the Inventory. Collected from the latest "Get User Inventory".

  • curRemainingUses - Returns the "Remaining Uses". Total number of remaining uses, if this is a consumable item.

    • Index - The Index to lookup from the Inventory. Collected from the latest "Get User Inventory".

  • curDisplayName - Returns the "Display Name". CatalogItem.DisplayName at the time this item was purchased.

    • Index - The Index to lookup from the Inventory. Collected from the latest "Get User Inventory".

  • curExpiration - Returns the "Expiration". Timestamp for when this instance will expire.

    • Index - The Index to lookup from the Inventory. Collected from the latest "Get User Inventory".

  • curPurchaseDate - Returns the "Purchase Date". Timestamp for when this instance was purchased.

    • Index - The Index to lookup from the Inventory. Collected from the latest "Get User Inventory".

  • loopInventory - The LoopIndex from the "For Each Inventory" through the Array of inventory items belonging to the user.​

  • countInventory - The Inventory Count from the Array of inventory items belonging to the user.


Get User Inventory :: Virtual Currency :

  • retCurrencyVal - Returns the "Currency Value". Value of the "Currency" that was inputted.

    • "" - The Currency to load from for the value.

  • retRechargeMax - Returns the "Recharge Max". Maximum value to which the regenerating currency will automatically increment.

    • "" - The Currency to load the value.

  • retRechargeTime - Returns the "Recharge Time". Server timestamp in UTC indicating the next time the virtual currency will be incremented.

    • "" - The Currency to load the value.

  • retSecondsToRecharge - Returns the "Seconds To Recharge". Time remaining (in seconds) before the next recharge increment of the virtual currency.

    • "" - The Currency to load the value.


Redeem Code :

  • redItemID - Returns the "Item ID". Unique identifier for the inventory item, as defined in the catalog.

    • Index - The Index to lookup from the Received List. Collected from the latest "Redeem Coupon".

  • redItemInstanceID - Returns the "Item Instance ID". Unique item identifier for this specific instance of the item.

    • Index - The Index to lookup from the Received List. Collected from the latest "Redeem Coupon".

  • redItemClass - Returns the "Item Class". Class name for the inventory item, as defined in the catalog.

    • Index - The Index to lookup from the Received List. Collected from the latest "Redeem Coupon".

  • redDate - Returns the "Purchase Date". Timestamp for when this instance was purchased.

    • Index - The Index to lookup from the Received List. Collected from the latest "Redeem Coupon".

  • redExpiration - Returns the "Expiration". Timestamp for when this instance will expire.

    • Index - The Index to lookup from the Received List. Collected from the latest "Redeem Coupon".

  • redRemainingUses - Returns the "Remaining Uses". Total number of remaining uses, if this is a consumable item.

    • Index - The Index to lookup from the Received List. Collected from the latest "Redeem Coupon".

  • redCatalogVersion - Returns the "Catalog Version" for the inventory item, when this instance was created.

    • Index - The Index to lookup from the Received List. Collected from the latest "Redeem Coupon".

  • redDisplayName - Returns the "Display Name". CatalogItem.DisplayName at the time this item was purchased.

    • Index - The Index to lookup from the Received List. Collected from the latest "Redeem Coupon".

  • redCurrency - Returns the "Unit Currency". Currency type for the cost of the catalog item.

    • Index - The Index to lookup from the Received List. Collected from the latest "Redeem Coupon".

  • redPrice - Returns the "Unit Price". Cost of the catalog item in the given currency.

    • Index - The Index to lookup from the Received List. Collected from the latest "Redeem Coupon".

  • loopReceived - The LoopIndex from the "For Each Received" through the Array of received items granted by the "Redeem Coupon".

  • countReceived - The Received Count from the Array of received items granted by the "Redeem Coupon".


Add User Virtual Currency :

  • addVirBalance - Returns the "Balance" of the virtual currency after modification.

  • addVirBalChange - Returns the "Balance Change". Amount added or subtracted from the user's virtual currency.

  • addVirPlayFabID - Returns the "PlayFabID". User currency that was added to.

  • addVirCurrency - Returns the "Virtual Currency". Name of the virtual currency which was modified.


Subtract User Virtual Currency :

  • subVirBalance - Returns the "Balance" of the virtual currency after modification.

  • subVirBalChange - Returns the "Balance Change". Amount added or subtracted from the user's virtual currency.

  • subVirPlayFabID - Returns the "PlayFabID". User currency that was subtracted from.

  • subVirCurrency - Returns the "Virtual Currency". Name of the virtual currency which was modified.


Server Response :

  • ServerResponse - Return the "Server Response" from every request from the PlayFab Server. The server response can also be shown in the "Chrome Developer Tools : Console", if in "debug mode".

Request :

  • Tag - Return the "Tag" of the latest request.

Server Setup

The Virtual Currencies with PlayFab is implemented by creating catalogs, a store list within and then virtual currencies for store trade and other transactions. It is easy to setup from the PlayFab Console, it only requires a few steps to set it from the server-side.

Catalogs.png

Step 1 : From the PlayFab Dashboard, select the Economy menu option. By default, the "Catalog" tab will initially show.

Step 2 : Click on the "New Catalog" button, then fill-up the configuration form.

Store Items.png

Step 3 : Once the catalog is created, press the "New Item" button.

Step 4 : An item creation configuration form will show, fill-up the necessary settings for the new item.

Currencies.png

Step 5 : Once your catalogs are set, you will need to setup your virtual currencies. Click on the "Currency" tab.

Step 6 : Finally, add and configure your new virtual currency that will be used on your app's virtual store.

Once you are done with the server configuration. You can then proceed adding and using the Virtual Currencies addon in your game application. Remember to enable the Virtual Currencies options and features from the PlayFab Settings - API Features and PlayFab Settings - Client Profile Options. And, sync the server's Client Profile Options to the client-side by configuring the settings on the PlayFab API addon.

After that, you're all set up to proceed in developing your game design. In event making while designing your game, remember to read the warnings below, there are hidden features that might break your game or at least confuse the developer, if without orientation.

Warning : Hidden Features

The Virtual Currencies addon, just like the other addons in the Construct Master Collection, is worked on a goal in covering all the essential features while still maintaining generality and ease of use.

In the case of the Virtual Currencies, the server requires different data types in passing data but the client-side (Construct 3) has a user-friendly design that can hide complexities by unifying the data types into a simple design, specifically instead of separately defining integers or floatswe simply use numbers.

 

That worked out well for all the addons in hiding the complexities, but the issue with this current implementation is that the developer has to input from both the store console and the client-side (application). Due to this, there will be different data types used, integers from the built-in PlayFab Debugger (F12) of the PlayFab Master Collection, the Server Response data and the records of the PlayFab Console. While numbers with decimals are used on the client-side.
 

There is a solution, a simple one is this warning documentation, it will sacrifice the standing of using the standard of making the labels and description self-documenting. Although, it's a trade-off worth tolerating, additional documentation and work in making a built-in converter is still worth it, in exchange for ease of use.
 

Now the ease of use of this implementation, is the Hidden Feature, it has a built-in converter from number to integer and vice-versa internally, the input and the output are always in numbers, ensuring the developer-side remains easy to manage, hence convenient for the addon users. Although, the server response and [F12] PlayFab Debugger will remain with the original integer data type.

The following actions, conditions and expressions are affected:

  • Actions

    • Add User Currency​

    • Subtract User Currency

    • Purchase Item​​

    • Advanced Purchase Item

  • Expressions​

    • curPrice

    • retCurrencyVal

    • redPrice

    • addVirBalance

    • addVirBalChange

    • subVirBalance

    • subVirBalChange

Basically, it only affects the price or amount value where it is sent or requested to and from the server as integers. But the addon applies the built-in converter of ( integer / 100 ) for the user input and output. Hence, from the server, a 100 worth of coin would just be 1.00 on the Construct 2 or Construct 3 editor.

Therefore, when inputting an amount or price parameter from the Virtual Currencies action, apply this formula ( integer / 100 ) , to get the number decimal version of the server integer, which the editor will automatically convert into integer internally but output from the expressions as still number decimals.

This is the hidden feature of the Virtual Currencies addon, for the convenience in event making.

Practical application will be explained below:

Server Store Item.png

Step 1 : From the PlayFab Dashboard, select the "Economy" menu option.

Step 2 : Open a catalog, and choose from an available store item.

Step 3 : Take note of its "Item ID" and "Amount" from a specific "Currency".

Purchase Item.png

Step 4 : Create an event with an action "Purchase Item" with an item id and virtual currency same from the server.

Step 5 : Although as you observer, the price or amount is different, that is as explained before, the one from the PlayFab Console is an integer data type, to convert into supporting number with decimals, you need to divide it by 100 to get client-side's counterpart value.

Step 6 : This is still the same case for the output expressions, the value will still be in numbers with decimals.

 

Step 7 : This applies to the other expressions and action parameters too. 

Purchase Item - Events.png

Step 8 : This is still a sample event for the implementation.

Observe that the price is in number with decimals.

Step 9 : As mentioned before, records from the PlayFab Console and the data sent and received to and from the server are still in integer, hence why the price in the [F12] PlayFab Debugger is still 1000.

Log - Release.png

Step 10 : But from the expressions outputted from the client-side (application), it is still in number with decimals, hence only 10 or 10.00.

That covers the hidden feature, I hope that you've learned well from this short lesson. Happy game development!

 
 
 
 
 

Easy Game Project

Sample Setup Project

Specifications

  • Instructions - The sample project has comments and instructions on how to use the addon and its features.

  • A.C.E. Coverage - It covers the implementation of each action, condition and expression.

  • Tips and Tricks - It provides some tips and tricks to a better use of the addon and of the event-sheet system alongside it.

Supporters

Only

Game Project

Sample Setup Project

Specifications

  • Instructions - The sample project has comments and instructions on how to use the addon and its features.

  • A.C.E. Coverage - It covers the implementation of each action, condition and expression.

  • Tips and Tricks - It provides some tips and tricks to a better use of the addon and of the event-sheet system alongside it.

Supporters

Only

Real Currencies

As the name says, the Virtual Currencies addon only handles virtual currencies and virtual products. But for real-life monetary value, use the Real Currencies addon where it accepts real currencies like USD.

Title Manager

The Virtual Currencies addon already can retrieve the catalog store listing, but the Title Manager addon, as the game manager, it can also retrieve the catalog store listing on its own unique way. And also do other game management features.

Get the tools

for your pro games!

Constuct Master Collection - Itch.io
Constuct Master Collection - Discord
Constuct Master Collection - Construct 3

© Construct Master Collection 2020 • All rights reserved

Contact Information: