1 of 71

v0.12.0

ENVIRONMENT SETUP

Overview

The basics

Welcome to PLAY (former READYgg) documentation!

The Getting Started describes the project requirements you need to meet to use PLAY SDK. The Install Dependencies describes the PLAY SDK dependencies and how to install them.

To quickly become proficient with the PLAY SDK, follow the integration steps in sequence. They will guide you through setting up and utilizing various features available on PLAY.

To review the supported features by the PLAY SDK, you can move to the modules section.

PLAY Sample Package

In case you want to see our sample DEMO scene implementation you need to use our Sample package.

Import the sample package by pasting following into your manifest.json file:

"io.getready.rgn.sample": "https://github.com/readyio/RGNSample.git#0.10.0-dev.529",

After the package is imported, you can see it in Unity Package manager (Window->Package Manager):

After you import the Sample, you'll see a new folder in your Assets folder. You can open the DEMO scene from the Sample. Unity will ask you to import the TextMeshPro Essentials in case you have not done it already

The DEMO sample scene looks like this:

By default the user is logged in as a guest user. So, everything you'll do, will be stored in the cloud. At the start you can visit the Store Test and try to buy some items.

If you click on Virtual Items you can see similar UI:

SDK Integration Guides

Getting Started

Structure

PLAY SDK (former READYgg SDK) is divided into multiple modules. Every module has its own functionality. All modules depend on the RGNCore module.

Unity

Unity integration

Tech Requirements

Unity integration

PLAY SDK requires the following software:

Unity 2020 LTS or later.
- It is always recommended to use a late version of Unity for bug fixes and up-to-date compatibility.

Prerequisites

Setup your bundle identifier in the project setting:

Open project settings Unity window: Edit->Project Settings...
Select Player and open the Other Settings section
For iOS tab change the Bundle Identifier
For Android tab change the Package Name

Android

Choose Minimum API Level 23 in Project Settings->Player->Other Settings

For Android, Target API Level should be 33 or higher for Google Play Store compliance.

Integration Support

If you are unable to find a solution in our documentation you can reach out to us directly by:

Step 1 - Import packages

Package Dependencies

In case you use an older version of Unity you need to add the Newtonsoft Json package. You can install it by pasting following into your manifest.json file:

In the new Unity versions the Newtonsoft Json is build in to Unity. No need to install the package.

Dependencies Installation:

Git package repository link. The easiest way to add the READYgg SDK into your project is to use PLAY package distribution. You need simply put the package git repository links into manifest.json file. See instructions below.

Troubleshooting : if you have error messages in Unity saying that it cannot find the git repository, make sure you have Git installed on your machine. Unity Hub needs it to import packages from Github.

Steps:

Open [project_dir]/Packages/manifest.json file in your favorite text editor
Paste following lines:

If you don't need some of the functionality, you can try to remove some modules.

The manifest.json file after all changes should look similar to this:

Afterwards switch to Unity and wait until the packages import finishes.

Steps:

Open Unity project
Click "+" button on left upper corner
Select "Add package from git URL..."
Paste the package links one by one:

Step 2 - Import credentials

Unity integration

Go on the and select your project.

Click on Download unity packages to download your project credentials.

Step 3 - Environments

Developers have access to two different environments:

Staging: Use this environment while developing and testing. This environment will use the testing blockchain backend.
Production: Use this environment for the releases, live versions available to users.

Example.

John started integrating the PLAY SDK in his application by setting the Staging environment.
He completed and tested feature Implementation in the Staging environment.
After that, he is ready to update the version in Stores, So he set Production and created new builds for store submission. He did a smoke test and updated in Stores.
After submitting to the stores, he switched back to the Staging environment to work on new features for their upcoming release.

Environment Setup

After setting up the above configuration data, you can switch Staging/Production environment from the Unity menu:

ReadyGamesNetwork->Set Staging

ReadyGamesNetwork->Set Production

Step 4 - Initialization

Unity integration

Structure

PLAY SDK is divided into multiple modules. Every module has its own functionality. All modules depend on the RGNCore module. In the current version, the modules are distributed by using packages for Unity Package Manager.

Obligatory modules/packages

RGNCore
RGNSignInEmail
RGNSignInGuest

PLAY Unity Initializer

We created an initialization script to automatically setup every module. This script can manage automatically the guest signIn and the modules initialization. To use it, simply create an empty GameObject in your starting scene and attach RGNUnityInitilizer.cs to it. With this script, you don't need to manually build the RGNCore and modules.

Access modules

To access modules you can use the "I" instance provider property:

var result = await [module_name].I.GetSomeResultAsync();

For example:

var purchaseResult = await StoreModule.I.BuyVirtualItemsAsync(itemIds);

Modules namespaces

The modules are located in the RGN.Modules.[module_name] namespaces. Here you can find a full list of modules with the namespaces:

Modules List

RGN.Modules.Achievement

RGN.Modules.Currency

RGN.Modules.GameProgress

RGN.Modules.Inventory

RGN.Modules.Messaging

RGN.Modules.Store

RGN.Modules.UserProfile

RGN.Modules.VirtualItems

RGN.Modules.Wallets

RGN.Modules.SignIn

RGN.Modules.Leaderboard

Unreal

Unreal Engine integration

Tech Requirements

Unreal integration

PLAY SDK requires the following software:

Unreal 5+
- It is always recommended to use a late version of Unreal for bug fixes and up-to-date compatibility.

Integration Support

If you are unable to find a solution in our documentation you can reach out to us directly by:

Creating a GitHub issue here
Dropping a message in our Discord dev-chat here

Step 1 - Import packages

Unreal Integration

Package Dependencies Installation:

Follow the link - https://github.com/readyio/rgn_unreal and clone it somewhere nearby the project directory.
Open the just pulled repository and copy the folder “Plugins” from it to the root of your project directory.
Open your project via Unreal Engine again and accept the offer to rebuild the modules.

Step 2 - Configure credentials

Unreal integration

Go on the developer dashboard and select/create your project.

Open the project settings and scroll down to the Plugins category and find the “ReadyGamesNetwork”, then fill the ProjectId and ApiKey fields by values from your console project.

Step 3 - Environments

Unreal integration

Developers have access to two different environments:

Staging: Use this environment while developing and testing. This environment will use the testing blockchain backend.
Production: Use this environment for the releases, live versions available to users.

Example.

John started integrating the READYgg SDK in his application by setting the Staging environment.
He completed and tested feature Implementation in the Staging environment.
After that, he is ready to update the version in Stores, so he set Production and created new builds for store submission. He did a smoke test and updated in Stores.
After submitting to the stores, he switched back to the Staging environment to work on new features for their upcoming release.

Environment Setup

After setting up the above configuration data, you can switch Staging/Production environment from the Unreal plugin setting menu:

ReadyGamesNetwork->Environment Target->Staging

ReadyGamesNetwork->Environment Target->Production

Step 4 - Initialization

Unreal integration

Open your level blueprint.

All blueprints nodes for PLAY SDK you can find in special category named “ReadyGamesNetwork”.

Add two core nodes to start work with the SDK - Core /Initialize and Core /Update.

Authentication

Integration Guide

Unity

Unity integration

Introduction

To interact with the PLAY API, you will need to be authenticated. This will allow you to store and retrieve additional user data in the PLAY ecosystem.

If the Auto Guest Login option in RGNUnityInitilizer.cs is checked, logging out from email will automatically sign you back in as guest.

using RGN;
using RGN.Modules.SignIn;
using UnityEngine;

public class AuthenticationChangedController : MonoBehaviour
{
    private void OnEnable()
    {
        RGNCore.I.AuthenticationChanged += OnAuthenticationChangedAsync;
    }
    private void OnDisable()
    {
        RGNCore.I.AuthenticationChanged -= OnAuthenticationChangedAsync;
    }

    private async void OnAuthenticationChangedAsync(AuthState authState)
    {
        switch (authState.LoginState)
        {
            case EnumLoginState.Success:
                Debug.Log("User is logged in");
                // You can start retrieving some data here
                break;
            case EnumLoginState.NotLoggedIn:
                Debug.Log("User is not logged in");
                break;
            case EnumLoginState.Error:
                Debug.LogError("On Auth error: " + authState.LoginState +
                    ", error: " + authState.LoginResult);
                break;
            default:
                Debug.LogError("Unhandled Login State: " + authState.LoginState);
                break;
        }
    }
}

using RGN.Modules.SignIn;

public class EmailLoginLogout : MonoBehaviour
{
    public void EmailSignIn()
    {
        // This call will open a web form
        // Handle the result in RGNCore.I.AuthenticationChanged event callback
        EmailSignInModule.I.TryToSignIn();
    }
    public void EmailSignOut()
    {
        EmailSignInModule.I.SignOut();
    }
}

Unreal

Unreal integration

Introduction

To interact with the PLAY API, you will need to be authenticated. This will allow you to store and retrieve additional user data in the PLAY ecosystem.

By default, the project is configured to automatically log into a guest account. This feature is enabled in the plugin settings.

If you require more control over this process, you can disable the checkbox and manually manage guest account logins.

User Profile

Integration Guide

Unity

Unity integration

Introduction

The user profile module is used to store user specific data related to his identity.

UserProfileData

userId (string): Unique READYgg ID for a user. Authenticated user has the same ID accross applications using READYgg.
email (string): Email of the authenticated user.
displayName (string): Authenticated user share the same display name accross applications using READYgg.
profilePicture (userProfilePicture): Authenticated user share the same profile picture accross applications using READYgg.
bio (string): Authenticated user share the same bio accross applications using READYgg.
currencies (List<Currency>): Contains all the currencies user collected for your application.

UserProfileData class methods

GetRGNCoinBalance();
- Return the amount of rgn-coin for this user.
GetCustomCoinBalance(string currencyName);
- Return the amount of your custom currency for this user.

Load User Profile

Update UserName/Display Name

Update User Bio

Retrieve User Currencies

"rgn-coin" Currency

Unreal

Unreal integration

Introduction

The user profile module is used to store user specific data related to his identity.

UserProfileData

userId (string): Unique READYgg ID for a user. Authenticated user has the same ID accross applications using READYgg.
email (string): Email of the authenticated user.
displayName (string): Authenticated user share the same display name accross applications using READYgg.
profilePicture : Authenticated user share the same profile picture accross applications using READYgg.
bio (string): Authenticated user share the same bio accross applications using READYgg.

Get User Profile

Update UserName/Display Name

Update User Bio

Get User Currencies

"rgn-coin" Currency

Virtual Items

Integration Guide

Introduction

Virtual items are game items, that can be purchased using game currency or can be rewarded as completing an . The Virtual item can also be minted an turn into NFT through the.

For example, a virtual item can be:

Racing Game: It can be different types of cars.
Puzzle game: It can be a bunch of hints pack.
Match-3 game: There can be different types of power-ups.
Shooting Game: Different types of guns, ammo etc

Virtual Items can be added using the . In order to retrieve your list of virtual items you can use the following API.

Unity

Unity integration

Introduction

Virtual items are game items, that can be purchased using game currency or can be rewarded as completing an Achievements. The Virtual item can also be minted an turn into NFT through the PLAY Dev Dashboard.

For example, a virtual item can be:

Racing Game: It can be different types of cars.
Puzzle game: It can be a bunch of hints pack.
Match-3 game: There can be different types of power-ups.
Shooting Game: Different types of guns, ammo etc

Virtual Items can be created using the PLAY Dev Dashboard.

VirtualItem

id (string): Unique id for the virtual item.
name (string): Name of the virtual item.
description (string): Description of the virtual item.
appIds (List<string>): List of project id where your item can be accessed.
createdAt (long): Date and time of the item creation.
updatedAt (long): Date and time of the last update on the item.
createdBy (string): User ID of the creator of the item
updatedBy (string): User ID of the last person who updated the item.
isStackable (bool): Indicate if the item can be stored under the same ID in the inventory.
tags (List<string>): List of tags to filter the items.
properties (List<Property>): List of properties you can store in json format to retrieve with the virtual item.
prices (List<PriceInfo>): List of prices defined for this item. Used to process transaction with the user's currencies.

Virtual item class methods

IsNFT();
- Return a bool to let you know if the virtual item is an NFT or not.
GetRGNCoinPrice();
- Return the price in rgn-coin if the item is an NFT.
GetCustomCoinPrice(string currencyName);
- Return the price based on your custom currency setup in the virtual item.

Get All Virtual Items for current app

using System.Collections.Generic;
using UnityEngine;
using RGN.Modules.VirtualItems;

public class VirtualItemExamples : MonoBehaviour
{
    public async void GetAllVirtualItem()
    {
        List<VirtualItem> virtualItems = await VirtualItemsModule.I.GetVirtualItemsAsync();
        foreach (var virtualItem in virtualItems)
        {
            Debug.Log($"Virtual item id : {virtualItem.id} \n" +
                $"virtual item name : {virtualItem.name}");
            // etc
        }
    }
}

Get with pagination

There is also a method overload for pagination requests. The pagination means you request not all items at once for the project. In this example every request contains 5 items. Each time you call the method, 5 more items will be loaded and added to the loaded item list.

using System.Collections.Generic;
using UnityEngine;
using RGN.Modules.VirtualItems;

public class VirtualItemExamples : MonoBehaviour
{
    private List<VirtualItem> allLoadedItems = new List<VirtualItem>();
    private VirtualItem lastLoadedItem = null;

    public async void GetVirtualItemsPaginationAsync()
    {
        List<VirtualItem> virtualItems = new List<VirtualItem>();
        if (allLoadedItems.Count > 0)
        {
            lastLoadedItem = allLoadedItems[allLoadedItems.Count - 1];
            virtualItems = await VirtualItemsModule.I.GetVirtualItemsAsync(5, lastLoadedItem.id); // Get 5 more items
        }
        else
        {
            virtualItems = await VirtualItemsModule.I.GetVirtualItemsAsync(5, ""); // Get 5 first items
        }
        allLoadedItems.AddRange(virtualItems);
        Debug.Log(allLoadedItems.Count);
    }
}

Different ways to retrieve virtual items :

Get by tags

using System.Collections.Generic;
using UnityEngine;
using RGN.Modules.VirtualItems;

public class VirtualItemExamples : MonoBehaviour
{
    public async void GetVirtualItemsAsync()
    {
        List<string> tags = new List<string> { "guns", "rifles" };
        List<VirtualItem> virtualItems = await VirtualItemsModule.I.GetByTagsAsync(tags);
    }
}

Get by ids

using System.Collections.Generic;
using UnityEngine;
using RGN.Modules.VirtualItems;

public class VirtualItemExamples : MonoBehaviour
{
    public async void GetByIdsAsync()
    {
        List<string> ids = new List<string> { "item_one_id", "item_two_id" };
        List<VirtualItem> virtualItems = await VirtualItemsModule.I.GetVirtualItemsByIdsAsync(ids);
    }
}

Updating Virtual Items data

using System.Collections.Generic;
using UnityEngine;
using RGN.Modules.VirtualItems;

public class VirtualItemExamples : MonoBehaviour
{
    public async void UpdateVirtualItemInfosAsync()
    {
        string virtualItemId = "some_virtual_item";
        await VirtualItemsModule.I.SetNameAsync(virtualItemId, "New Virtual Item Name");
        await VirtualItemsModule.I.SetDescriptionAsync(virtualItemId, "New Virtual Item Description");

        List<string> newTags = new List<string> { "tag01", "tag02" };
        await VirtualItemsModule.I.SetTagsAsync(virtualItemId, newTags);
    }
}

Storing and getting custom json data :

It is possible the store and retrieve custom properties json string associated with virtual item. The json string should be UTF8 formatted string not longer than 100k characters.

using UnityEngine;
using RGN.Modules.VirtualItems;

[System.Serializable]
public struct MyCustomVirtualItemData
{
    public int MyInt;
    public string MyString;
    public float MyFloat;
}

public class VirtualItemExamples : MonoBehaviour
{
    public async void UpdatePropertiesAsync()
    {
        string virtualItemId = "some_virtual_item";

        var myCustomData = new MyCustomVirtualItemData()
        {
            MyFloat = 42.78f,
            MyInt = 51,
            MyString = "Hello World"
        };
        string propertiesJson = JsonUtility.ToJson(myCustomData);
        await VirtualItemsModule.I.SetPropertiesAsync(virtualItemId, propertiesJson);
    }

    public async void GetPropertiesAsync()
    {
        string virtualItemId = "some_virtual_item";

        var jsonProperties = await VirtualItemsModule.I.GetPropertiesAsync(virtualItemId);
        MyCustomVirtualItemData myCustomData = JsonUtility.FromJson<MyCustomVirtualItemData>(jsonProperties);

        Debug.Log(myCustomData.MyString);
    }
}

Updating and downloading the virtual item image :

using UnityEngine;
using RGN.Modules.VirtualItems;

public class VirtualItemExamples : MonoBehaviour
{
    public async void UpdateVirtualItemImageAsync(string virtualItemId, Texture2D virtualItemImage)
    {
        byte[] bytes = virtualItemImage.EncodeToPNG();
        await VirtualItemsModule.I.UploadImageAsync(virtualItemId,bytes);
    }
}

To download virtual item image you can use following code:

using UnityEngine;
using RGN.Modules.VirtualItems;
using RGN.Model;
using System.Threading.Tasks;

public class VirtualItemExamples : MonoBehaviour
{
    public async Task<Texture2D> DownloadVirtualItemImageAsync(string virtualItemId)
    {
        byte[] bytes = await VirtualItemsModule.I.DownloadImageAsync(virtualItemId, ImageSize.Small);
        Texture2D resultTexture = new Texture2D(1, 1);
        resultTexture.LoadImage(bytes);
        resultTexture.Apply();
        return resultTexture;
    }
}

Buy virtual items

To buy virtual items, please refer to the Store Module.

Unreal

Unreal integration

Introduction

For example, a virtual item can be:

Racing Game: It can be different types of cars.
Puzzle game: It can be a bunch of hints pack.
Match-3 game: There can be different types of power-ups.
Shooting Game: Different types of guns, ammo etc

Virtual Items can be created using the PLAY Dev Dashboard.

VirtualItem

id (string): Unique id for the virtual item.
name (string): Name of the virtual item.
description (string): Description of the virtual item.
appIds (List<string>): List of project id where your item can be accessed.
createdAt (long): Date and time of the item creation.
updatedAt (long): Date and time of the last update on the item.
createdBy (string): User ID of the creator of the item
updatedBy (string): User ID of the last person who updated the item.
isStackable (bool): Indicate if the item can be stored under the same ID in the inventory.
tags (List<string>): List of tags to filter the items.
properties (List<Property>): List of properties you can store in json format to retrieve with the virtual item.
prices (List<PriceInfo>): List of prices defined for this item. Used to process transaction with the user's currencies.

Get Virtual Items

Get Virtual Items with pagination

Get Virtual Items by tags

Get Virtual Items by ids

Set Virtual Item properties

Get Virtual Item properties

Download Virtual Item image

Inventory

Integration Guide

Unity

Unity integration

Introduction

After the user purchases a Virtual Item, it is automatically added to the user's Inventory during the transaction process. It is possible also to add a virtual item to the user's inventory without going through the purchase process for non-NFT items.

InventoryItem

id (string): Unique inventory id for this item.
virtualItemId (string): Id of the virtual item stored in the inventory.
quantity (int): Amount of items store in this inventory slot.
appIds (List<string>): List of project id where this item will be accessible.
tags (List<string>): List of tags used for filtering items.
properties (List<Property>): List of properties for this inventory item.

Retrieving inventory items with Virtual Items data

The following method gets all inventory items for the currently logged in player.

using System.Collections.Generic;
using UnityEngine;
using RGN.Modules.Inventory;

public class InventoryExamples : MonoBehaviour
{
    private async void GetUserInventory()
    {
        List<InventoryItemData> inventory = await InventoryModule.I.GetWithVirtualItemsDataForCurrentAppAsync();
        foreach (var inventoryItem in inventory)
        {
            Debug.Log($"Virtual item id : {inventoryItem.virtualItemId}");
            Debug.Log($"Virtual item name : {inventoryItem.virtualItem.name}");
        }
    }
}

Add to inventory

Add to inventory can be use to add regular virtual items into the player inventory. NFT's cannot be added to the inventory with this function.

using UnityEngine;
using RGN.Modules.Inventory;

public class InventoryExamples : MonoBehaviour
{
    private async void AddToUserInventory()
    {
        string virtualItemId = "virtualItemToAdd";
        await InventoryModule.I.AddToInventoryAsync(virtualItemId);
    }
}

Set Properties

using UnityEngine;
using RGN.Modules.Inventory;

public struct MyCustomProperties
{
    public int BonusHealth;
    public float DamageMultiplier;
}

public class InventoryExamples : MonoBehaviour
{
    private async void SetPropertiesInInventory()
    {
        string inventoryItemId = "inventoryItemId";

        MyCustomProperties customProperties = new MyCustomProperties
        {
            BonusHealth = 50,
            DamageMultiplier = 1.5f
        };
        string jsonProperties = JsonUtility.ToJson(customProperties);

        await InventoryModule.I.SetPropertiesAsync(inventoryItemId, jsonProperties);
    }
}

Get properties

using UnityEngine;
using RGN.Modules.Inventory;

public struct MyCustomProperties
{
    public int BonusHealth;
    public float DamageMultiplier;
}

public class InventoryExamples : MonoBehaviour
{
    private async void GetPropertiesInInventory()
    {
        string inventoryItemId = "inventoryItemId";
        string jsonProperties = await InventoryModule.I.GetPropertiesAsync(inventoryItemId);
        MyCustomProperties customProperties = JsonUtility.FromJson<MyCustomProperties>(jsonProperties);
        Debug.Log($"Bonus health : {customProperties.BonusHealth} \n" +
            $"Damage multiplier : {customProperties.DamageMultiplier}");
    }
}

Unreal

Unreal integration

Introduction

InventoryItem

id (string): Unique inventory id for this item.
virtualItemId (string): Id of the virtual item stored in the inventory.
quantity (int): Amount of items store in this inventory slot.
appIds (List<string>): List of project id where this item will be accessible.
tags (List<string>): List of tags used for filtering items.
properties (List<Property>): List of properties for this inventory item.

Get inventory items

Add to inventory

Add to inventory can be use to add regular virtual items into the player inventory. NFT's cannot be added to the inventory with this functionality.

Get inventory item properties

Set inventory item properties

Store

Integration Guide

Unity

Unity integration

Introduction

The users can buy Virtual Items either individually or in packs. After a virtual item is purchased it will be added to the user's inventory. You can use the to create new store offers and virtual items.

Each store offer can contain one or more virtual items to sell. Price info data is also part of the store offer. It is also possible to sell virtual items without creating store offers.

StoreOffer

id (string): Unique id or the store offer.
name (string): Name of the store offer.
description (string): Description of the virtual item.
appIds (List<string>): List of project id where your store offer can be accessed.
createdAt (long): Date and time of the store offer creation.
updatedAt (long): Date and time of the last update on the store offer.
createdBy (string): User ID of the creator of the store offer.
updatedBy (string): User ID of the last person who updated the store offer.
tags (List<string>): List of tags to filter the store offers.
time (TimeInfo): Contains the time infos for your store offer.
itemIds (List<string>): List of items available in your store offer
prices (List<PriceInfo>): List of prices defined for this store offer. Used to process transaction with the user's currencies.
properties (List<Property>): List of properties you can store in json format to retrieve with the store offer.

Buy Virtual Items and Store offers

In case the virtual item contains prices information

Purchase from store offer

Get store offer

Buy Virtual Items NFT

In order to purchase NFTs, there is some additional check you will need to do to make sure the user has all the requirements. Here's an example:

Unreal

Unreal integration

Introduction

Each store offer can contain one or more virtual items to sell. Price info data is also part of the store offer. It is also possible to sell virtual items without creating store offers.

StoreOffer

id (string): Unique id or the store offer.
name (string): Name of the store offer.
description (string): Description of the virtual item.
appIds (List<string>): List of project id where your store offer can be accessed.
createdAt (long): Date and time of the store offer creation.
updatedAt (long): Date and time of the last update on the store offer.
createdBy (string): User ID of the creator of the store offer.
updatedBy (string): User ID of the last person who updated the store offer.
tags (List<string>): List of tags to filter the store offers.
time (TimeInfo): Contains the time infos for your store offer.
itemIds (List<string>): List of items available in your store offer
prices (List<PriceInfo>): List of prices defined for this store offer. Used to process transaction with the user's currencies.
properties (List<Property>): List of properties you can store in json format to retrieve with the store offer.

Get Store Offers

Buy Virtual Items and Store offers

Currency (IAP)

Integration Guide

Unity

Unity integration

Introduction

Every project may have multiple custom currencies. For example "diamonds" and/or "cash". Aside from these typical game currencies, projects wishing to sell NFTs must integrate a specific currency. The internal name for this currency is "rgn-coin". When the "rgn-coin" is presented in the UI it can have any currency name, for example, "gems".

The "rgn-coin" can only be sold using in-app purchases. For more information, please refer to the Currency GDG.

Other typical currencies can be added and used in an expected manner - as rewards to the user's account, or sold for in-app purchases.

We suggest utilizing Unity's IAP Package to handle the in-app purchase process on Android and iOS.

Purchase `rgn-coin` (IAP required)

Purchasing rgn-coin works a bit differently, it has its own API called PurchaseRGNCoinAsync(string iapUUID)

We recommend using the latest version of the Unity IAP plugin.

You will need to get the transactionId and receipt from the PurchaseEventArgs when the in app purchase is completed.

rgn-coin Products

10 rgn-coin :

"uid": "4a13bcd3-ff64-43a4-8c13-e978d968f68c",
"priceInUSD": 0.99,
"quantity": 10

20 rgn-coin :

"uid": "0eeae85c-c9af-47f0-8df4-56a4442c23d7",
"priceInUSD": 1.99,
"quantity": 20

30 rgn-coin :

"uid": "9d2ed68b-2a6c-45d4-bc07-29f256799943",
"priceInUSD": 2.99,
"quantity": 30

50 rgn-coin :

"uid": "b7bcbbf6-753d-47dd-8bff-93b4539c825d",
"priceInUSD": 4.99,
"quantity": 50

110 rgn-coin :

"uid": "b81e8e95-59a6-4a77-b1bc-f5b7d6eacfa4",
"priceInUSD": 9.99,
"quantity": 110

300 rgn-coin :

"uid": "f35c4f83-cf22-4723-828a-66e8069614eb",
"priceInUSD": 24.99,
"quantity": 300

500 rgn-coin :

"uid": "3c814835-9f6f-4947-98f0-6e70964b887d",
"priceInUSD": 39.99,
"quantity": 500

1000 rgn-coin :

"uid": "b65994dc-ecfd-4549-ab32-51e196947c8b",
"priceInUSD": 69.99,
"quantity": 1000

Add rgn-coin to user

using UnityEngine;
using RGN.Modules.Currency;
using UnityEngine.Purchasing;

public class CurrenciesExamples : MonoBehaviour
{
    public PurchaseProcessingResult ProcessPurchase(PurchaseEventArgs purchaseEvent)
    {
        bool validPurchase = true; // Presume valid for platforms with no R.V.

        if (validPurchase)
        {
            Debug.Log($"Product {purchaseEvent.purchasedProduct.definition.id} Purchased");
            string transactionId = purchaseEvent.purchasedProduct.transactionID;
            string receipt = purchaseEvent.purchasedProduct.receipt;
            
            PurchaseRGNCoinAsync(transactionId, receipt);
        }
        else
        {
            Debug.LogError($"Something happened when trying to purchase product {purchaseEvent.purchasedProduct.definition.id}");
        }

        return PurchaseProcessingResult.Complete;
    }

    public async void PurchaseRGNCoinAsync(string transactionId, string receipt)
    {
        string rgnProductId = "4a13bcd3-ff64-43a4-8c13-e978d968f68c"; // 10 rgn-coin
        await CurrencyModule.I.PurchaseRGNCoinAsync(rgnProductId, transactionId, receipt);
    }
}

Get user rgn-coin

using System.Collections.Generic;
using UnityEngine;
using RGN.Modules.Currency;

public class CurrenciesExamples : MonoBehaviour
{
    public async void GetRgnCoinCurrenciesAsync()
    {
        List<Currency> currencies = await CurrencyModule.I.GetUserCurrenciesAsync();
        Currency readyCurrency = currencies.Find(x => x.name.Equals("rgn-coin"));
        Debug.Log($"User has {readyCurrency.quantity} rgn-coin");
    }
}

Custom currencies

Add soft currencies to user

using System.Collections.Generic;
using UnityEngine;
using RGN.Modules.Currency;

public class CurrenciesExamples : MonoBehaviour
{
    public async void AddSoftCurrenciesAsync()
    {
        Currency goldCurrency = new Currency
        {
            name = "gold",
            quantity = 10
        };
        List<Currency> currenciesToAdd = new List<Currency> { goldCurrency };
        await CurrencyModule.I.AddUserCurrenciesAsync(currenciesToAdd);
    }
}

Get user soft currencies

using System.Collections.Generic;
using UnityEngine;
using RGN.Modules.Currency;

public class CurrenciesExamples : MonoBehaviour
{
    public async void GetSoftCurrenciesAsync()
    {
        List<Currency> currencies = await CurrencyModule.I.GetUserCurrenciesAsync();
        Currency goldCurrency = currencies.Find(x => x.name.Equals("gold"));
        Debug.Log($"User has {goldCurrency.quantity} gold");
    }
}

Unreal

Unreal integration

Introduction

The "rgn-coin" can only be sold using in-app purchases. For more information, please refer to the .

Other typical currencies can be added and used in an expected manner - as rewards to the user's account, or sold for in-app purchases.

Purchase `rgn-coin` (IAP required)

Purchasing rgn-coin works a bit differently, it has its own API called PurchaseRGNCoinAsync(string iapUUID)

You will need to get the transactionId and receipt when the in app purchase is completed.

rgn-coin Products

10 rgn-coin :

20 rgn-coin :

30 rgn-coin :

50 rgn-coin :

110 rgn-coin :

300 rgn-coin :

500 rgn-coin :

1000 rgn-coin :

Get user rgn-coin quantity

Add rgn-coin to user

Custom currency

Get user custom currency quantity

Add custom currency to user

Achievements

Integration Guide

The AchievementsModule allows to give the user different rewards for making progress. The first things you'll need to decide are when you want to reward the user and what should be given as a reward.

Currently, the achievements support 3 types of user rewards:

Virtual Items rewards - the virtual items are added to the user's inventory
Currency Coins rewards - the currency coins are added to the user's data. It is not possible to give the "rgn-coin" as a currency reward here.
Progression rewards - If you want to track user progress. You can use custom progression data types and store those in the user's data. When the achievement is completed and the progression rewards are given, it will increment the user's progression values accordingly. The progression values should be numbers. To retrieve the progression data you need to use the GameProgressModule: method.

You can create new achievements by using the developer dashboard or by reaching out to the PLAY team.

Unity

Unity integration

Introduction

Achievements can be used to reward the player following some specific actions in your game. He can be rewarded with currencies, virtual items, progression or leaderboard score.

AchievementData

id (string): Unique id for this achievement.
requestName (string): Name use to call the achievement by a user friendly name.
name (string): Name of the achievement.
description (string): Description of the achievement.
rewards (List<Reward>): List of rewards when this achievement is finish and claimed. See Achievement Reward Data for more informations.
setBy (string): Let you know who can trigger this achievement (server or client).
isClaimable (bool): Let you know if the achievement is ready to be claimed.
valueToReach (int): Value to reach in order to claim this achievement.
completedAchievementsToUnlock (List<string>): List of other achievements required to unlock this one.
repeatable (bool): Let you know if this achievement can the triggered and claimed multiple time.
repeatNoMoreOftenThanCron (string): Let you set a period where this achievement can be repeated (daily, weekly, monthly). Can be set using cron setting.
startTime (long): The start time of this achievement. Cannot be triggered before this date.
endTime (long): The end time of this achievement. Cannot be triggered after this date.
resetTimeLimitEvery (string): Reset the start and end time based on a cron setting.

Achievement Reward Data structure

type
- The reward type : currency, progression, item_by_id, setLeaderboardScore, addLeaderboardScore.
name
- The name of the reward.
quantity
- The quantity of the reward that will be given to the user upon completing the achievement.
  - For "item_by_id" and "currency", it represents the number of items or coins rewarded.
  - For "progression", it represents the increment value for the user's progression.
  - For "setLeaderboardScore", it represents the score that will be set for the current user to the leaderboard
  - For "addLeaderboardScore", it represents the score that will be added for the current user to the leaderboard
appIds
- List of project id where the rewards will be given.

Get game achievements

Get user achievements

This function returns the completed and on going achievements for the user.

Trigger achievement by id

Trigger achievement by request name

Claim achievement by id

If the achievement is not set to be automatically claimed when completed, you can claim it in game to show to the player the rewards he received.

Claim achievement by request name

If the achievement is not set to be automatically claimed when completed, you can claim it in game to show to the player the rewards he received.

Unreal

Unreal integration

Coming soon

Game Progress

Integration Guide

Unity

Unity integration

Introduction

In the Game Progress module, you will be able to store game specific data related to the user progression.

Set Custom User Data

You can store your custom serialized classes in our database:

using UnityEngine;
using RGN.Modules.GameProgress;

[System.Serializable]
public class CustomUserData
{
    public int HitPoints;
    public int RegenerateHealth;
    public int HealthRegenDelay;
    public int HealthRegenRate;
    public string SomeString;
    public string[] Bookmarks;
    public float Health;
}

public class GameProgressExamples : MonoBehaviour
{
    public async void StoreCustomDataAsync()
    {
        var customData = new CustomUserData()
        {
            HitPoints = 10,
            RegenerateHealth = 10,
            HealthRegenDelay = 39,
            SomeString = "Hello World",
            Bookmarks = new string[] { "bookmark_1", "bookmark_2" },
            Health = 3.14f
        };
        UpdateUserLevelResponseData<CustomUserData> customUserData = await GameProgressModule.I.UpdateUserProgressAsync(customData, null);
        Debug.Log($"Updated hit points : "+ customUserData.playerProgress.HitPoints);
    }
}

Get Custom User Data

You can get your custom serialized classes in our database:

using UnityEngine;
using RGN.Modules.GameProgress;

[System.Serializable]
public class CustomUserData
{
    public int HitPoints;
    public int RegenerateHealth;
    public int HealthRegenDelay;
    public int HealthRegenRate;
    public string SomeString;
    public string[] Bookmarks;
    public float Health;
}

public class GameProgressExamples : MonoBehaviour
{
    public async void GetCustomDataAsync()
    {
        var customUserData = await GameProgressModule.I.GetUserProgressAsync<CustomUserData>();
        Debug.Log($"Retrieved hit points : "+ customUserData.playerProgress.HitPoints);
    }
}

Unreal

Unreal integration

Introduction

In the Game Progress module, you will be able to store game specific data related to the user progression.

Set Custom User Data

Get Custom User Data

Leaderboards

Integration Guide

The LeaderboardModule is responsible for managing player scores and ranking players according to their totals. This module provides various functionalities such as setting player scores, getting leaderboard data, and fetching player entries on the leaderboard.

Using the LeaderboardModule

You can use the module to perform a variety of leaderboard-related operations:

Get Leaderboard By ID

Retrieve leaderboard data by providing a idto the GetLeaderboardByIdAsync() method.

public async Task<LeaderboardData> GetLeaderboardByIdAsync(string id)

The LeaderboardData contains the following fields:

LeaderboardData

id (string): Unique id of the leaderboard.
name (string): Leaderboard name. Is used also to store the localization key for the name.
description (string): Leaderboard description. Is used also to store the localization key for the description.
invertSortOrder (bool): Sorting direction. False implies that places are sorted in descending order, while true means places are sorted in ascending order.
decimalOffset (int): This parameter determines how many digits of the score integer are displayed after the decimal point. The size of the decimal part. For example, with decimalOffset: 2, the number 1234 will be displayed as 12.34.
type (string): The leaderboard type that determines the results unit. Possible values: numeric — Number, time — Time in milliseconds.
autoResettable (bool): Determines whether the leaderboard should automatically reset.
resetEveryTimeAtCron (string): A Cron expression to specify the reset period.
rewardsAtReset (LeaderboardReward[]): Rewards which will be earned at the reset period.
requiredToJoin (JoinRequirement[]): A list of requirements that must be met when a user joins a leaderboard. Joining here means adding and setting user scores. Currently, three types are supported. Please see the JoinRequirement description for more information.
createdAt (long): Date and time when the leaderboard was created. This field is automatically populated by the backend.
updatedAt (long): Date and time when the leaderboard was last time updated. This field is automatically populated by the backend.
createdBy (string): User Id who created the leaderboard. This field is automatically populated by the backend.
updatedBy (string): User Id who last time updated the leaderboard. This field is automatically populated by the backend.

LeaderboardReward

placeFrom (int): The starting position from which users will earn the reward.
placeTo (int): The ending position up to which users will earn the reward.
achievementId (string): Specifies the reward. It includes various types of rewards like virtual items rewards, currency rewards, etc, linked with a specific achievement ID.

JoinRequirement

type (string): The type of the join requirement. Currently 3 types are supported:
- gamepass - The user must have a gamepass to join the leaderboard.
- item_by_id - A specific virtual item identified by its ID must exist in the user's inventory.
- item_by_tag - At least one virtual item in the user's inventory with the provided tag must exist.
id (string): The value for the different type criterias.
- gamepass - The game pass id.
- item_by_id - The virtual item id.
- item_by_tag - The virtual item tag.

Get Leaderboard By Request Name

Retrieve leaderboard data by providing a requestName to the GetLeaderboardByRequestNameAsync() method.

public async Task<LeaderboardData> GetLeaderboardByRequestNameAsync(string requestName)

Get Leaderboard IDs

Retrieve all leaderboard IDs defined for the current project by calling GetLeaderboardIdsAsync() method.

using System.Collections.Generic;
using RGN.Modules.Leaderboard;
using UnityEngine;

namespace SomeNamespace
{
    internal sealed class GetLeaderboards
    {
        public async void GetLeaderboardsAsync()
        {
            List<string> leaderboardIds =
                await LeaderboardModule.I.GetLeaderboardIdsAsync();
            for (int i = 0; i < leaderboardIds.Count; ++i)
            {
                Debug.Log("Leaderboard id: " + leaderboardIds[i]);
            }
        }
    }
}

Set Player Score

Set a player's score on a leaderboard by using the SetScoreAsync() method. This method requires leaderboardId, score, and optionally extraData as parameters.

using RGN.Modules.Leaderboard;
using UnityEngine;

namespace SomeNamespace
{
    internal sealed class SetPlayerScore
    {
        public async void SetPlayerScoreAsync(string leaderboardId)
        {
            int playerPlace =
                await LeaderboardModule.I.SetScoreAsync(leaderboardId, 42);
            Debug.Log("Player place after setting the score: " +
                playerPlace);
        }
    }
}

Set Player Score with custom data

Set a player's score on a leaderboard by using the SetScoreAsync() method with the optional parameter extraData

using RGN.Modules.Leaderboard;
using UnityEngine;

namespace SomeNamespace
{
    internal sealed class SetPlayerScoreWithCustomData
    {
        [System.Serializable]
        public struct PlayerData
        {
            public string DisplayName;
            public string Description;
            public int Kills;
            public int Deaths;
        }

        public async void SetPlayerScoreWithCustomDataAsync(
            string leaderboardId,
            PlayerData playerData)
        {
            int playerPlace = await LeaderboardModule.I.SetScoreAsync(
                leaderboardId,
                69,
                JsonUtility.ToJson(playerData));
            Debug.Log("Player place after setting the score: " +
                playerPlace);
        }
    }
}

Get User Entry

Fetch a player's entry from a specific leaderboard by calling GetUserEntryAsync(). This method requires the leaderboardId as a parameter.

using RGN.Modules.Leaderboard;
using UnityEngine;

namespace SomeNamespace
{
    internal sealed class GetUserEntry
    {
        public async void GetUserEntryAsync(string leaderboardId)
        {
            LeaderboardEntry result = 
                await LeaderboardModule.I.GetUserEntryAsync(leaderboardId);
            var sb = new System.Text.StringBuilder();

            sb.Append("User ID: ").AppendLine(result.userId);
            sb.Append("Score: ").AppendLine(result.score.ToString());
            sb.Append("Formatted Score: ").AppendLine(result.formattedScore);
            sb.Append("Place: ").AppendLine(result.place.ToString());
            sb.Append("Extra Data: ").AppendLine(result.extraData);

            Debug.Log(sb.ToString());
        }
    }
}

Get Entries

To display user rankings, use the GetEntriesAsync() method. This method takes leaderboardId, quantityTop, includeUser, and quantityAroundUser as parameters.

using System.Collections.Generic;
using RGN.Modules.Leaderboard;
using UnityEngine;

namespace SomeNamespace
{
    internal sealed class GetEntries
    {
        public async void GetEntriesAsync(string leaderboardId)
        {
            List<LeaderboardEntry> results = 
                await LeaderboardModule.I.GetEntriesAsync(
                    leaderboardId,
                    quantityTop: 10,
                    includeUser: true,
                    5);

            for (int i = 0; i < results.Count; ++i)
            {
                LeaderboardEntry result = results[i];
                var sb = new System.Text.StringBuilder();
                sb.Append("User ID: ").AppendLine(result.userId);
                sb.Append("Score: ").AppendLine(result.score.ToString());
                sb.Append("Formatted Score: ").AppendLine(result.formattedScore);
                sb.Append("Place: ").AppendLine(result.place.ToString());
                sb.Append("Extra Data: ").AppendLine(result.extraData);

                Debug.Log(sb.ToString());
            }
        }
    }
}

You can create and manage leaderboards by using the developer dashboard or by reaching out to the PLAY team.

Unity

Unity integration

The LeaderboardModule is responsible for managing player scores and ranking players according to their scores. This module provides various functionalities such as setting player score, getting leaderboard data, fetching player entries on the leaderboard and more.

LeaderboardData

id (string): Unique id of the leaderboard.
name (string): Leaderboard name. Is used also to store the localization key for the name.
description (string): Leaderboard description. Is used also to store the localization key for the description.
invertSortOrder (bool): Sorting direction. False implies that places are sorted in descending order, while true means places are sorted in ascending order.
decimalOffset (int): This parameter determines how many digits of the score integer are displayed after the decimal point. The size of the decimal part. For example, with decimalOffset: 2, the number 1234 will be displayed as 12.34.
type (string): The leaderboard type that determines the results unit. Possible values: numeric — Number, time — Time in milliseconds.
autoResettable (bool): Determines whether the leaderboard should automatically reset.
resetEveryTimeAtCron (string): A Cron expression to specify the reset period.
rewardsAtReset (LeaderboardReward[]): Rewards which will be earned at the reset period.
requiredToJoin (JoinRequirement[]): A list of requirements that must be met when a user joins a leaderboard. Joining here means adding and setting user scores. Currently, three types are supported. Please see the JoinRequirement description for more information.
createdAt (long): Date and time when the leaderboard was created. This field is automatically populated by the backend.
updatedAt (long): Date and time when the leaderboard was last time updated. This field is automatically populated by the backend.
createdBy (string): User Id who created the leaderboard. This field is automatically populated by the backend.
updatedBy (string): User Id who last time updated the leaderboard. This field is automatically populated by the backend.

Unreal

Unreal integration

Coming soon

Matchmaking

Integration Guide

Unity

Unity integration

The Matchmaking Module acts as the central management system for all matchmaking procedures within the PLAY. It boasts an array of functionalities designed to facilitate the initiation, participation, voting, and termination of matches.

The primary functionality of the matchmaking module is to allow PvP matchmaking for synchronous gameplay.

Additional functionality referred to as "Voting" throughout this document allows for a matchmaking system wherein the winner is determined by votes cast by other players.

Therefor the Matchmaking module can be utilized for either PvP synchronous gameplay matches, or for the voting approach - the two styles do not have both be utilized.

Using the MatchmakingModule

Properties:

type (string): Identifies the match's type. Currently, only "default" is supported.
finishType (string): Describes how a match concludes, either through manual input or based on score submission.
startType (string): Outlines how a match commences, either manually or based on match filling.
maxUsers (int): Designates the maximum number of users permitted in the matchmaking process.
isStarted (bool): Indicates if the matchmaking process has been initiated.
votingEnabled (bool): Defines whether voting is permitted during the matchmaking process.
oncePerUserVoting (bool): Dictates whether a user can only vote once throughout the matchmaking process.
createdBy (string): The identifier of the user who initiated the matchmaking process. This value is updated by the backend.
updatedBy (string): The identifier of the user who last updated the matchmaking data. This value is updated by the backend.
createdAt (long): The timestamp denoting the creation time of the match. This value is updated by the backend.
updatedAt (long): The timestamp marking the most recent update of the matchmaking data. This value is updated by the backend.
participants (list of strings): Contains user identifiers of all participants involved in the matchmaking process.
votes (list of Vote objects): Stores the votes cast during the matchmaking process.
participantsScore: A dictionary that maps participant identifiers to their respective scores during the matchmaking process.
participantsPayload: A dictionary that maps participant identifiers to their respective optional payload data during the matchmaking process.

Lifecycle of a Match

Initially, all getter methods return empty lists, implying no current match.

Here's a step-by-step overview of a match's lifecycle:

A match is created with the settings provided via CreateMatchAsync(). By default, the user who created the match becomes a participant if participateInOnCreate is set to true.
GetJoinOpenMatchesAsync() returns the newly created match.
Other users join the match using ParticipateInMatchAsync().
Once the match fills up, it either begins automatically if matchFillBased is selected, or manually by invoking StartMatchAsync().
If votingEnabled is true, non-participating users can vote for participating users through VoteForMatchAsync(). To retrieve matches with voting enabled, use GetVoteOpenMatchesAsync().
If votingEnabled is false, participating users can submit their scores using SubmitMatchScoreAsync().
The match ends automatically if finishType is set to scoreSubmitBased once all users have submitted their scores, or it can be ended manually via FinishMatchAsync() in case the manual setting was submitted at the start.
The finished matches can be requested by calling the GetFinishedMatchesAsync() method.

Additional Features

The backend currently supports several features that the Unity SDK does not:

participateFee: An array of currencies. Users need to pay with these provided currencies to participate in the match.
voteFee: An array of currencies. Users need to pay with these provided currencies to vote for other users.
createMatchAchievements: A list of achievements with rewards given to the user who creates the match.
participateMatchAchievements: A list of achievements with rewards given to users who participate in the match.
startMatchAchievements: A list of achievements with rewards given to the user who starts the match.
voteForMatchAchievements: A list of achievements with rewards given to the user who votes for other users.
winnerMatchAchievements: A list of achievements with rewards given to users who win the match.
finishMatchAchievements: A list of achievements with rewards given to all users who participate in the match upon its conclusion.

Should you require any of the above features or have requests for additional features, please inform the PLAY team.

CreateMatchAsync

Description

The CreateMatchAsync method within the MatchmakingModule class is designed to asynchronously create a matchmaking match, based on the provided match configuration.

This method offers an asynchronous operation, returning a Task<MatchmakingData>, which represents the created match.

Parameters

MatchmakingData matchConfig: The configuration for the match to be created. This cannot be null.
bool participateInOnCreate: Optional parameter that determines whether the user participates in the match upon its creation. The default value is true.
Dictionary<string, object> participatePayload: Optional parameter that provides additional data for user participation. The default value is null.
CancellationToken cancellationToken: Optional parameter to enable the cancellation of the task. The default value is an unset CancellationToken.

Exceptions

ArgumentNullException: Thrown when matchConfig is null.
OperationCanceledException: Thrown when the operation is cancelled via the cancellationToken.

Example

Here's an example usage of the CreateMatchAsync method:

Ensure to handle the possible exceptions for a smooth user experience. Always make sure matchConfig is not null before passing it to the method.

ParticipateInMatchAsync

Description

The ParticipateInMatchAsync method in the MatchmakingModule class allows a user to asynchronously participate in a matchmaking match, identified by the provided match ID.

The method performs an asynchronous operation, returning a Task<string> that signifies the ID of the match that the user has participated in.

Parameters

string matchId: The ID of the match to participate in. This value cannot be null or empty.
Dictionary<string, object> participantPayload: Optional parameter that provides additional data for user participation. The default value is null.
CancellationToken cancellationToken: Optional parameter to enable the cancellation of the task. The default value is an unset CancellationToken.

Exceptions

ArgumentNullException: Thrown when matchId is null or empty.
OperationCanceledException: Thrown when the operation is cancelled via the cancellationToken.

Example

Here's an example usage of the ParticipateInMatchAsync method:

Be sure to handle possible exceptions to ensure a seamless user experience. Always confirm that matchId is not null or empty before passing it to the method.

StartMatchAsync

Description

The StartMatchAsync method in the MatchmakingModule class allows for asynchronously starting a matchmaking match, identified by the provided match ID.

The method provides an asynchronous operation, returning a Task<string> that represents the ID of the match that has been started.

Parameters

string matchId: The ID of the match to start. This value cannot be null or empty.
CancellationToken cancellationToken: Optional parameter to enable the cancellation of the task. The default value is an unset CancellationToken.

Exceptions

ArgumentNullException: Thrown when matchId is null or empty.
OperationCanceledException: Thrown when the operation is cancelled via the cancellationToken.

Example

Here's an example usage of the StartMatchAsync method:

Always handle possible exceptions to ensure a seamless user experience. Make sure that matchId is not null or empty before passing it to the method.

VoteForMatchAsync

Description

The VoteForMatchAsync method in the MatchmakingModule class enables the casting of a vote asynchronously for a matchmaking match, identified by the provided match ID and participant ID.

The method conducts an asynchronous operation, returning a Task<string> that signifies the ID of the match for which the vote has been cast.

Parameters

string matchId: The ID of the match to vote for. This value cannot be null or empty.
string participantId: The ID of the participant casting the vote. This value cannot be null or empty.
CancellationToken cancellationToken: Optional parameter to enable the cancellation of the task. The default value is an unset CancellationToken.

Exceptions

ArgumentNullException: Thrown when matchId or participantId is null or empty.
OperationCanceledException: Thrown when the operation is cancelled via the cancellationToken.

Example

Here's an example usage of the VoteForMatchAsync method:

Always handle possible exceptions to ensure a seamless user experience. Ensure both matchId and participantId are not null or empty before passing them to the method.

SubmitMatchScoreAsync

Description

The SubmitMatchScoreAsync method in the MatchmakingModule class enables a user to asynchronously submit the score for a matchmaking match, identified by the provided match ID.

The method provides an asynchronous operation, returning a Task<string> that signifies the ID of the match for which the score has been submitted.

Parameters

string matchId: The ID of the match for which the score is being submitted. This value cannot be null or empty.
long score: The score to be submitted for the match.
CancellationToken cancellationToken: Optional parameter to enable the cancellation of the task. The default value is an unset CancellationToken.

Exceptions

ArgumentNullException: Thrown when matchId is null or empty.
OperationCanceledException: Thrown when the operation is cancelled via the cancellationToken.

Example

Here's an example usage of the SubmitMatchScoreAsync method:

Always handle possible exceptions to ensure a seamless user experience. Make sure matchId is not null or empty before passing it to the method.

FinishMatchAsync

Description

The FinishMatchAsync method in the MatchmakingModule class allows a user to asynchronously finish a matchmaking match, identified by the provided match ID.

The method executes an asynchronous operation, returning a Task<string> that represents the ID of the match that has been finished.

Parameters

string matchId: The ID of the match to finish. This value cannot be null or empty.
CancellationToken cancellationToken: Optional parameter to enable the cancellation of the task. The default value is an unset CancellationToken.

Exceptions

ArgumentNullException: Thrown when matchId is null or empty.
OperationCanceledException: Thrown when the operation is cancelled via the cancellationToken.

Example

Here's an example usage of the FinishMatchAsync method:

Always handle possible exceptions to ensure a seamless user experience. Confirm that matchId is not null or empty before passing it to the method.

GetJoinOpenMatchesAsync

Description

The GetJoinOpenMatchesAsync method in the MatchmakingModule class allows for asynchronously retrieving a list of open matches that a user can join.

The method executes an asynchronous operation, returning a Task<List<MatchmakingData>> that represents the list of open matches that the user can join.

Parameters

int limit: An integer indicating the maximum number of matches to retrieve.
string startAfter: An optional parameter representing a match ID after which to start retrieving the matches. The default value is an empty string.
CancellationToken cancellationToken: Optional parameter to enable the cancellation of the task. The default value is an unset CancellationToken.

Returns

Task<List<MatchmakingData>>: A task that represents the asynchronous operation. The task result contains a list of MatchmakingData objects, which are the open matches available for joining.

Example

Here's an example usage of the GetJoinOpenMatchesAsync method:

Always handle possible exceptions to ensure a seamless user experience. You can modify the limit and startAfter parameters to fit your application's specific needs.

GetVoteOpenMatchesAsync

Description

The GetVoteOpenMatchesAsync method in the MatchmakingModule class allows for asynchronously retrieving a list of open matches that a user can vote on. Some matches may have voting enabled, allowing users to vote for match participants.

The method executes an asynchronous operation, returning a Task<List<MatchmakingData>> that represents the list of open matches that the user can vote on.

Parameters

int limit: An integer indicating the maximum number of matches to retrieve.
string startAfter: An optional parameter representing a match ID after which to start retrieving the matches. The default value is an empty string.
CancellationToken cancellationToken: Optional parameter to enable the cancellation of the task. The default value is an unset CancellationToken.

Returns

Task<List<MatchmakingData>>: A task that represents the asynchronous operation. The task result contains a list of MatchmakingData objects, which are the open matches available for voting.

Example

Here's an example usage of the GetVoteOpenMatchesAsync method:

Always handle possible exceptions to ensure a seamless user experience. You can modify the limit and startAfter parameters to fit your application's specific needs.

GetFinishedMatchesAsync

Description

The GetFinishedMatchesAsync method in the MatchmakingModule class allows for asynchronously retrieving a list of finished matches.

The method executes an asynchronous operation, returning a Task<List<MatchmakingData>> that represents the list of finished matches.

Parameters

int limit: An integer indicating the maximum number of matches to retrieve.
string startAfter: An optional parameter representing a match ID after which to start retrieving the matches. The default value is an empty string.
CancellationToken cancellationToken: Optional parameter to enable the cancellation of the task. The default value is an unset CancellationToken.

Returns

Task<List<MatchmakingData>>: A task that represents the asynchronous operation. The task result contains a list of MatchmakingData objects, which are the finished matches for the current app.

Example

Here's an example usage of the GetFinishedMatchesAsync method:

Always handle possible exceptions to ensure a seamless user experience. You can modify the limit and startAfter parameters to fit your application's specific needs.

GetFinishedMatchByIdAsync

Description

The GetFinishedMatchByIdAsync method in the MatchmakingModule class allows for asynchronously retrieving data of a finished match by its ID. If the match does not exist or is from another application, the method throws an exception.

The method executes an asynchronous operation, returning a Task<MatchmakingData> that represents the data of the finished match.

Parameters

string matchId: The ID of the finished match.
CancellationToken cancellationToken: Optional parameter to enable the cancellation of the task. The default value is an unset CancellationToken.

Returns

Task<MatchmakingData>: A task that represents the asynchronous operation. The task result contains the MatchmakingData of the finished match.

Example

Here's an example usage of the GetFinishedMatchByIdAsync method:

Always handle possible exceptions to ensure a seamless user experience. You can modify the matchId parameter to retrieve the data of any specific finished match by its ID.

Unreal

Unreal integration

Coming soon

Wallets

Integration guide

In order to purchase NFTs the user needs to create a crypto wallet. During wallet creation, the user must provide a password to access the wallet later. It is important to inform the user that the password must be written down or otherwise stored since neither PLAY nor developers can recover the wallet password if forgotten. The NFT virtual items are sold for "" currency.

The wallet creation is handled automatically through the OAuth form based on your game requirement. The user will be prompt to create a wallet if needed when trying to signIn.

Unity

If you are selling an NFT in your game, it is important to check the following :

Is user authenticated with a email?

Is user has a wallet?

Create wallet

Example flow for NFT purchase

Unreal

Unreal integration

Coming soon

Analytics

Integration guide

Analytics events can be visualized on the developer dashboard.

Unity

Log event

using UnityEngine;
using RGN.Modules.Analytics;

public class AnalyticExamples : MonoBehaviour
{
    private async void LogCustomEvent()
    {
        await AnalyticsModule.I.LogEventAsync("player_purchased_car_01");
    }
}

Unreal

Unreal integration

Coming soon

Notifications

Integration Guide

Unity

Unity integration

The MessagingModule class contains various methods that are used for subscribing and unsubscribing to topics, sending messages to a particular user (for admin users only), and receiving messages from the messaging service.

Currently supported topics:

RGN.Modules.Inventory.InventoryModule.ITEM_ADDED_EVENT_TOPIC - this event is triggered when a new virtual item is added to the user's inventory by using the RGN.Modules.Inventory.InventoryModule.AddToInventoryAsync method.
RGN.Modules.Inventory.InventoryModule.ITEM_REMOVED_EVENT_TOPIC - this event is triggered when an inventory item is removed by using the RGN.Modules.Inventory.InventoryModule.RemoveByInventoryItemIdAsync method.

The Subscribe method is used to subscribe the message receiver to a particular topic:

void Subscribe(string topic, IMessageReceiver messageReceiver)

IMessageReceiver interface is intended to be implemented by classes that want to receive and handle messages. The IMessageReceiver interface defines a single method named OnMessageReceived, which takes two parameters - a string named topic and an object of the type Message.

The topic parameter is used to identify the specific topic or channel that the message was sent on and the message parameter contains the actual message data.

The Unsubscribe method is used to unsubscribe the message receiver from a particular topic.

Here is a code example:

using UnityEngine;
using RGN.Modules.Messaging;

public class MessagingExamples : MonoBehaviour, IMessageReceiver
{
    private void Start()
    {
        // TODO: use module constants for topic parameter, for example:
        // RGN.Modules.Inventory.InventoryModule.ITEM_ADDED_EVENT_TOPIC
        MessagingModule.I.Subscribe("it_is_better_to_use_module_constants", this);
    }

    private void OnDestroy()
    {
        MessagingModule.I.Unsubscribe("it_is_better_to_use_module_constants", this);
    }

    public void OnMessageReceived(string topic, Message message)
    {
        Debug.Log($"New message received for topic : {topic}, message : {message}");
    }
}

The sample above shows an implementation of the IMessageReceiver interface in a class called SomeNotificationReceiver. This class inherits from MonoBehaviour, which is a Unity class that allows for the creation of scripts that can be attached to game objects in a Unity scene.

The SomeNotificationReceiver class subscribes to a specific message topic by calling the MessagingModule.I.Subscribe method and passing in the topic string and an instance of itself as the message receiver. It also unsubscribes from the same topic in its OnDestroy method by calling the MessagingModule.I.Unsubscribe method.

The OnMessageReceived method simply logs a message to the Unity console with the topic and message received. You can implement your own message handling code.

Unreal

Unreal integration

Coming soon

Module Requests

List of features available to be added to the SDK

PLAY has developed and deployed on iOS and Android a variety of in-game features that are not yet a part of our SDK. We continuously add these features to the SDK as developers request them - You can review the list here and get in touch if there's a particular feature you'd like integrated into the SDK!

PLAY Feature List

Rewarded Ads: Watch ads for a currency or item reward
Friends: persistent friends across the ecosystem
Online Friends Menu: Invite online friends to start a game, see who is online and what they are playing
Direct Messaging: text chat with friends
Voice Chat & Calls: Call a friend, or use voice chat during a multiplayer game
Emotes: For multiplayer gameplay
Activity Centre: surface announcements and social notifications to players
Creator Tools: allow players to create content in your game - support for any type of asset
Social Feed: Infinitely scrolling, supports trending and followed content
Post Creation Tools: Allow players to create and share posts

Game Design Guides

Overview

Guides on Player-Facing Implementation of PLAY Modules

So you've got a handle on how to integrate PLAY's SDKs into your game's code - but what about the in-game side of integration? All of PLAY's modules have been deployed live and undergone analytics-driven tuning to determine the most effective ways to implement the features in-game.

This section of PLAY's documentation is devoted to sharing these learnings and best practices for Web3 integration with you. A companion Game Design Guide is available for each of our modules that will provide you with examples of in-game UI/UX + illustrate various ways you can modify each module's in-game behaviour to suit your needs!

We hope that these Game Design Guides (to be referred to as GDG in the rest of the documentation) will help you save some time in planning your next Web3 feature integration, or spark some inspiration for the latest GDD you are working on!

User Authentication

Benefits and Use Cases

Feature Overview

PLAY's User Authentication Module allows a player to create a new PLAY account or log in to their existing one with email and password. Players with an account have their progress saved non-locally, which triggers several benefits both for you and your players. This feature also serves as the foundation for enabling Web3 functionality to leverage in your game.

Key Benefits

Restore Game Progress: Players who uninstall the game can pick back up where they left off by logging in with their account. No lost progress! This functionality is doubly important if the player has made non-consumable purchases in your game.
Multiple Device Play: Players can play the game on whatever devices they have available and switch between them as desired.
Simple Sign-In: Players simply choose an email and password to create an account.
Cross-Game/Platform Friends with Web3: If your game has multiplayer or social components and as such has a friends feature - players who log in with an existing PLAY account will automatically have access to their friends. For example, Alice is friends with Bob in Game A. They log in to Game B with the same credentials they used in Game A. Bob and Alice are now in each other's friends list in Game B!
Casual, Mobile-Friendly NFTs & Crypto Wallet: PLAY's Web3 Tech Stack is enabled by the user authentication feature. For example, a player needs a crypto wallet to hold any NFTs they purchase or earn in your game. READYgg's modules allow for a super simple wallet creation flow once a player has an account. For more details and images of how the NFT flow is managed in-game see the GDG for the Store.

In-Game Implementation: No Previous User Authentication

The below describes the general approach to adding user authentication to a game that previously had no user authentication. For titles that already have a way for players to create an account, see the next section. When it comes to triggering user authentication to prompt a player to make an account there are two primary approaches commonly seen in games today.

On Game Launch: When a player loads your game for the first time a title screen is shown with buttons prompting the player to either make an account or continue as a guest. The Guest option is often relegated to normal text while the account creation options are given larger more enticing buttons. If a player chooses to proceed as a guest the account creation options can be accessed from a menu (like settings) in-game.

On mobile platforms, this method is usually seen in titles related to extremely strong IP related to well-known brands. If you are not affiliated with such a brand it would be wise to monitor your onboarding funnel with analytics events for each step that the player will tap or click through. It is common to lose a significant portion of players at the account creation step when triggered on the launch/title screen!

Player Triggered: This represents the most common approach. When a player starts the game they are automatically playing as a guest account and must trigger account creation themselves. The game's settings menu is the most common location to allow the player to sign in and out.

A third less common approach can be seen in mobile titles with social systems integrated into their core loop: A hard currency bonus gifted to the player for creating an account. This strategy allows developers to call attention to their login options (usually still in the settings menu) and also increase the number of players that create an account.

In-Game Implementation: Existing Account Creation

The following describes the approach for adding PLAY account creation & login to a game or project that already has account creation. The primary difference is how onboarding players are approached in terms of flow and theming.

For example, a game that already has many registered users might opt to frame user authorization as wallet creation, instead of account creation. Likely this game would also eschew the approach of on-launch PLAY authorization - if players already have accounts using that flow would lack clarity and likely off-put players.

User Profile

Benefits and Use Cases

Feature Overview

PLAY's User Profile by default supports a player username and profile photo that players can customize in-game. Players can customize the profile picture by uploading a photo from their camera roll. The username is the minimum requirement - meaning you have the freedom to implement the profile in-game in such a way that suits your game.

A player's in-game currency wallet (not to be confused with a crypto wallet) is also associated with their profile. Currency includes any existing currencies in your game + RGN-Coins - a special virtual currency obtainable only via IAP and used for purchasing NFT virtual items. See the Currency and Virtual Items guides for more details.

Key Benefits

Persistent Player Identity: If the player has set a username and picture in a different PLAY title then it will be automatically filled in your game when they log in.
Flexible: Implement the UI/UX in-game based on your needs.

In-Game Implementation

In order to enable PLAY's complete tech stack players must sign in or create their PLAY account. The most minimal in-game implementation will involve displaying the username of the player so they have visual confirmation that they have successfully signed in with the proper account.

The profile photo element is optional, and whether or not it makes sense to include both the player username and photo is largely determined by the genre of your game.

Multiplayer titles where the player does not control an avatar are the most common use case for utilizing both a customizable name and profile photo.

For example, multiplayer poker games have an emphasis on the player's identity and skill but not so much emphasis that a fully customizable avatar is required - making the profile photo a perfect choice.

If you have a single-player game where the player controls an avatar then it is entirely optional to include a customizable profile photo - players already have an identity in the form of their avatar.

Game (Progression + Rewards)

Benefits and Use Cases

Feature Overview

For titles where levels or matches are played, the Game Module allows you to track player progress and give rewards when a level/match is completed.

Key Benefits

Customizable: You are able to customize the trigger for progression (for example, after completing a level in a puzzle game, or after winning a match in a MOBA) and also enter custom rewards. Currency or XP rewards are supported by default, and you may also set up custom rewards to give, like crafting material or reward boxes.

In-Game Implementation

There are some best practices to keep in mind when it comes to giving your player some rewards for completing a level or match. It's common in a variety of genres across platforms to take a moment and clearly communicate what your player has earned and, often, have them manually tap or press a button to claim their rewards. The goal here is to alleviate potential confusion for players on the type and quantity of rewards they receive - and as a result, minimize emails for support from players who incorrectly think they didn't receive a reward!

If you also give a player rewards when they level up make sure to take a similar approach! An animation is sufficient without rewards, but if rewards are given consider triggering a modal or screen to allow the player to claim them.

Virtual Items

Benefits and Use Cases

Feature Overview

As stated in the integration tutorial, Virtual Items are any game item players collect, equip, use, etc. Virtual items may also be consumable or upgradeable. Players may purchase them, get them as rewards, or earn them from achievements - pretty much every case you may need (plus some bonus functionality!) can be handled with our Virtual Items module.

The primary distinction to keep in mind is between Virtual Items and NFT Virtual Items. This distinction becomes relevant for players when they are purchasing or acquiring NFT-Virtual Items, as they need to have a crypto wallet to store the NFT.

Key Benefits

Easy to Use: The elusive dashboard. Not everyone has time to build a nice web interface to help you manage all that content. And you won't have to! With PLAY's Virtual Items dashboard adding new virtual items is simple to learn for any team member.
Live Content Updates: PLAY's virtual item systems let you enable or disable virtual items available for sale without releasing a new version - allowing for more granular content updates outside of version releases (or disabling a bugged item that went live!)
Simple Minting: Refreshingly easy. After creating your virtual item just head on over to the Minting Desk to select it and get minting!
Modifiable: If you require additional functionality not included in the SDK you may attach your own data in JSON format to virtual items.

In-Game Implementation

There are as many options for virtual items implementation as they are game genres, so the in-game examples here will highlight consumable (referred to as "stackable" in the integration tutorial) items vs. non-consumable items.

Power-ups are employed in a variety of genres. In the below example, the player has a limited supply of 2 types of power-ups, infinite use of a basic power-up, and a new power-up that will be unlocked when they progress further.

Design-wise, the power-up that is non-consumable covers the case of a player who runs out of the more effective, consumable power-ups. Depending on your target audience and how resources are consumed, you may consider safeguards such as this to prevent a player from failing to a certain inventory state that would be difficult or tedious for them to overcome.

As for non-consumable items, anything from fashionable dresses to battle-hardened rifles goes. Virtual Items can have purely cosmetic effects like in the example below or function like a typical piece of equipment in an RPG that modifies stats and requires upgrades to reach its full potential.

Previewing is good! It's always good to let a player have a large, clear view of an item - especially when it's purely cosmetic.

For items that modify stats, make sure to be clear on the most critical information. If you intend to monetize a piece of equipment the reason why it is good should be upfront and center. Sometimes, this may work like highlighting the % stat improvement that merchandised item provides over the player's currently equipped item.

Currency (IAP)

Benefits and Use Cases

Feature Overview

The Currency In-App Purchase Module deals with any regular virtual currency you would like to sell via IAP + includes our purpose-built currency - RGN-Coins.

In order to sell NFT Virtual Items to players you must require the player to purchase those NFTs with RGN-Coins.

There are several reasons for this requirement, one of the most important is the need for payment verification to safeguard against cheaters. Payment verification for In-App Purchases is not simple to develop and the large majority of games will, when necessary, find other ways to identify cheaters and then restrict them for certain parts of the game.

RGN-Coins also allow you to leverage Web3 strategies in your game without disrupting your existing economy.

Key Benefits

Mobile App Store Compliant: Purchasing an NFT virtual item in the same manner as a regular virtual item (with in-game currency) is compliant with iOS and Android.
Verified In-App Purchases: Since NFTs minted in the ecosystem contain $RDYX and as a result have real value, a cheater would actually be stealing money from a developer by using an in-app payment exploit for currency to spend on an NFT. With PLAY's currency IAP module, your minted NFTs will be safeguarded from any cheaters sneaking around in your game!
White-Label: RGN-Coins is our internal name for the secured currency to purchase NFTs. You may choose any player-facing name and icon design that works for your game's theme - gems, orbs, diamonds, whatever fits best!

In-Game Implementation Examples

RGN-Coins fall under the "Hard Currency" classification for in-game currencies. This means it's a premium currency that may only be acquired in large quantities via IAP. A typical hard currency will usually have a few sources for free players to acquire small amounts over time, and your game likely already has a currency that fits this description. RGN-Coins differ in that it is only acquired by IAP.

Of course, the best practices for merchandising the IAP bundles and price points remain the same as any typical currency purchase. The screen capture below illustrates 3 common merchandising strategies that you may want to incorporate in your currency shop.

Most Popular & Best Value Banners: RGN-Coins are balanced to give the best value at the most expensive purchase, so the placement would be similar to what we see above. Your in-house currency may vary! The placement of the "Most Popular" is commonly a merchandising tactic rather than a reflection of popularity. A/B testing different placements will help you determine the optimal placement to increase your monetization KPI (a safe starting point would be the first purchase that gives a discount/bonus!)
Purchase Bonus Percentage: Everybody wants to get the most out of their money. Make sure to communicate the bonus currency (as shown above) or discount percentage of your currency IAP bundles! This approach is seen in a huge variety of game stores - and it makes logical sense to communicate to players that they get a better deal for spending more money.
Purchase ThumbnailI Design: It's always nice to update the visuals alongside indicating the quantity of currency to reflect the increase. It adds visual polish and additionally can be digested at a glance compared to utilizing numbers alone.

Store

Benefits and Use Cases

Feature Overview

The Store module provides you with a multitude of ways to implement, test, and refine an optimal merchandising strategy for your game. You can list a selection of permanent store offers with single or multiple items, trigger special store offers by date and time, employ varied pricing strategies, and categorize and filter store offers using tags!

And of course, anything you can do with a regular virtual item being sold in your store can also be done with an NFT virtual item!

We also provide an additional safeguard to ensure the best experience for players while addressing the limited quantity nature of NFTs.

You may set the total quantity available for store purchase to match the number of NFTs you minted (note that this property is only available for NFT virtual items, not regular virtual items).

Once the entire supply of NFTs has been sold, the store purchase will be automatically hidden. You wouldn't want to merchandise an item to a player that they can't actually buy!

Key Benefits

Customizable Purchase Contents: Support for selling individual items or bundles of multiple items! You have the flexibility to configure the best array of purchases and item combinations for your specific store.
Pricing Flexibility: Multiple options for optimizing your pricing strategy are available. Set the price in a single currency or a combination of currencies! Support for displaying discounts is also included, perfect to use in conjunction with a limited-time store bundle.
Store Offer Scheduling: Easily plan a schedule of limited-time offers to increase monetization. Want to create a limited-time store offer with a discount to run during the holiday weekend? Have a refreshing daily deals section? No problem - the store module has you covered.
Categorize by Tags: Titles that monetize heavily on multiple categories of virtual items inevitably require filtering support for their stores. This functionality comes with our Store Module, simply add tags to your virtual items and then use those tags to allow players to filter the store in-game.
Modifiable: If you require additional functionality not included in the SDK you may attach your own data in JSON format to virtual items or store offers!
Interoperable: Our modules also support interoperability for developers who wish to enable this functionality. An example of interoperability would be purchasing an emote in the shop for Game A and then automatically having access to that emote in Game B (the player must also use the PLAY account in both Game A and B).

In-Game Implementation Examples

As covered above, there's a lot you can do with the Store Module. The implementation examples will focus on 3 different use cases that can provide extensive value for your monetization strategies regardless of genre.

Merchandising NFT Virtual Items

When merchandising NFTs in your game it is first and foremost important to integrate them into the game world and communicate their utility and/or rarity. We recommend theming the NFT items like any other player-facing feature or mechanic in your game. An NFT dog might be a "Rare Breed," and an NFT fashion item can be a "Limited Edition." This approach holds true even if you are a Web3 project, you'll still want to theme the NFT class of items to match the game.

However, it's also important to communicate that the items are in fact NFTs. We recommend integrating an information modal to explain NFTs to players and allow them to navigate to the PLAY player dashboard to learn more if they are so inclined. This approach in combination with theming the NFT items has been highly successful in a conversion rate of up to 42% and a 74% lift to ARPDAU.

The below image shows an example where NFT-backed virtual items are merchandised as "Limited Editions" and given a separate store entry placement from regular items.

The above image shows the tutorialization of NFTs in a social game with a casual audience.

The information modals would trigger when a player viewed the "Limited Editions" shop for the first time and could be manually triggered again by tapping a "?" button placement on that screen.

An alternative option is to simply use a manually triggered information modal - that approach may be a better fit for a less casual game and has been used in several other integrations.

Limited-Time Shop Offers

The above example illustrates an NFT virtual item being merchandised in a similar fashion to a limited-time IAP - with the modification of being a hard currency purchase.

This is just one example of possible configurations, limited-time offers could also be used to set up a daily deals section within your in-game shop.

Filtering Items in Your Shop

If you have a large library of virtual items that you merchandise to players in a store, you probably need filters. Even a medium amount of items could still benefit from filters, depending on your store's UI/UX.

It's important to make browsing your store simple, and even intuitive when possible, so players can just focus on picking up whatever purchases they are looking for. Any typical gamer probably has at least one example of a game they played where the shop or inventory experience had a painfully large amount of items and no easy way to categorize them (we won't name names though)!

Thankfully, you can organize your virtual items with tags and then surface those to players as categories or filters in your store. See the image below for an in-game example.

Performing inventory management can be a really fun, or a really terrible part of a game.

Make sure to carefully consider what types of categories for items would be most useful to players when they are browsing the store or viewing their inventory.

The more items you have, the more granular you might want to be.

Inventory

Benefits and Use Cases

Feature Overview

When players buy or earn virtual or NFT virtual items those items are added to their inventory. The Inventory module is primarily supportive - players need somewhere to stash their items!

Key Benefits

NFT & Regular Virtual Items: A player's NFT virtual items acquired in the game are also a part of their regular inventory in addition to being in their crypto wallet. This means if the player happens to lose their crypto wallet password, they lose the ability to transfer or stake their NFT virtual items, but their ability to access and use those items in-game remains unaffected.
Upgradeable: Upgrading is a must-have feature in a wide variety of games, so our inventory supports the upgrading of non-consumable items. This means you can have upgradeable heroes, equipment, etc.
Modifiable: If you require additional functionality not included in the SDK you may attach your own data in JSON format to virtual items used in the inventory.
Flexible: Implement the UI/UX in-game based on your needs.
Interoperable: Our modules also support interoperability for developers who wish to enable this functionality. An example of interoperability would be purchasing an emote in the shop for Game A and then automatically having access to that emote in the player inventory of Game B (the player must also use the PLAY account in both Game A and B).

In-Game Implementation Examples

Inventory is yet another case where the implementation is going to depend on the genre and audience of your game.

For example, a match-3 inventory will allow players to check their unlocked and available boosters. If the player has zero of a booster there might be a button for a player to "Get More" that will take them to the store. The purpose of the inventory screen is for a player to check their current supply. See the image below for an example of a simple supply-based inventory of powerups.

Consider instead an RPG where the player can manage the various equipment on their character.

The UI/UX implementation of that inventory can vary wildly since players are making comparisons and strategic choices between multiple pairs of boots (and how they work with the rest of the equipment), not just checking if they have any boots left.

It's always a good idea to find some references in games with similar requirements to see what you think works well or doesn't work well about their inventory system. It's a great way to make some informed decisions when planning your implementation.

Achievements

Benefits and Use Cases

Feature Overview

Nearly any game can benefit from an achievement system! The achievements module allows you to track progress for specific actions a player takes in your game. You can optionally add rewards for completing achievements in the form of currency or virtual items and also set specific achievements to be repeatable.

You can also optionally give NFT virtual items as rewards for achievements if desired - this would be a great way to reward engaged players who focus on completing achievements.

However, note that NFTs that are given as rewards to players may not be infused with $AURA and are instead NFTs in the traditional sense.

Therefore NFT items given as rewards are still compelling collectables for players but the health of the ecosystem token economy is preserved.

Key Benefits

On-Chain Achievements: You can allow a player to view their achievements from all supported ecosystem titles or from specific titles in the ecosystem if you choose. Achievements are also tracked as part of the player's ecosystem profile.
Flexible: Implement the achievement types & in-game UI/UX that best suit your needs.
Support for Varied Rewards Types: If desired you may assign various reward types for achievement completion. Have players collect badges for completing achievements, or set up an achievement structure that guides and rewards players new to the game.

In-Game Implementation

The types of actions you use to create your achievements are largely determined by your goals for the feature, and how involved you want players to be in the achievements system overall.

Do you want to give achievements only for the very hardest tasks that a player can do? You might consider making tough, repeatable achievements that provide a source of currency.

Looking to onboard new players? You can use achievements like a trail of breadcrumbs for players to follow as they progress through the game, gathering rewards as they discover and explore. Your achievements in that case will likely focus on giving rewards or even just XP for completing unique actions a small number of times.

Another possibility is to add a new layer of prestige for your most engaged players by leveraging achievements as a system to allow them to collect a set of NFT rewards. When creating the balancing for your achievements you can aim to create enough difficulty that players will be required to sink resources and/or spent significant effort in-game - thereby incentivizing desired behaviour as players aim to collect the complete set of NFTs!

In parallel to your creation of achievement types and balancing, you'll also need a place to host your achievements in-game, and possibly also trigger some communication to player when they get progress. See the image below for an example.

Some titles might opt to include achievements as part of the profile, others may give achievements their own distinct menu.

You'll also want to include someplace for a player to read how they might complete the achievement - in the above example, achievements look like badges so players tap to open a detail window.

You may also choose to let players know when they complete achievements, like in the example above. If doing so would disrupt your game flow in a way you'd like to avoid, you could instead add a callout to the achievements menu so the player can navigate there in their own time.

NFT Purchase Flow & Wallets

Benefits & Use Cases

Feature Overview

PLAY's proprietary crypto wallet provides a mobile app store-compliant & casual user-friendly solution for leveraging Web3 strategies in your game.

PLAY's wallet is non-custodial, which translates to players maintaining exclusive control of their wallet. This also keeps things simple and familiar for players, no prior knowledge of Web3 is required since creation is managed simply by setting a password.

Some existing Web3 games require a wallet at the moment the game is launched, but for certain platforms or audiences, this might be a bit offputting to players looking to try a game for the first time. PLAY's Wallet Module allows you to incorporate wallet creation at the time of your choosing, whether it's at launch or day 7.

The only time the wallet is required is when players are purchasing or claiming an NFT virtual item for the first time - giving you the flexibility to determine why, how, and when to prompt players to create a wallet.

Key Benefits

Mobile App Store Compliant: PLAY's SDK allows you to integrate Web3 on iOS and Android! Check the In-Game Implementation section for an example of a compliant NFT purchasing flow.
Casual User Friendly: It's not necessary for the player to be versed in Web3! They need only be versed in wanting to play your game or getting that awesome sword.
External Wallet Support: Players of course have the option to move their NFTs out of PLAY's proprietary wallet, with Metamask being our initially supported option. More options will be added as players or developers request!
One-Time Setup: The wallet is associated with a player's PLAY account. This means the player will only need to set up their wallet one time, in one game. After that, if they log in to another game in the ecosystem they will automatically have access to their wallet & be able to purchase or claim NFTs with no extra steps.

In-Game Implementation

Developers maintain the ability to determine the best place to trigger account & wallet creation - you know your player funnels best! However, platform-based regulations (in particular on Android and iOS) mean that in order to get your submission accepted you should follow an implementation like the flow shown below.

The flow below illustrates how a player can purchase an NFT in your game on a mobile platform. If a player has an account, a wallet, and enough currency, they complete their purchase normally. Whether the player has enough currency and is logged in is handled in-game - whether or not the player has a wallet is handled in the oAUTH form.

In order for players to create a wallet in your game they'll need to set a password. This is included as part of the oAUTH flow in the web form.

For Web2 titles migrating to Web3, we do recommend keeping it simple like the above example - there were no issues with player onboarding in previous integrations that triggered account and wallet creation on NFT purchase.

Depending on your audience you may choose to implement a bit more tutorialization, see the NFT Merchandising section of the Store guide for an example.

Limited-Time Offers

Benefits and Use Cases

Feature Overview

Limited-Time Offer IAPs are an incredibly effective feature for monetization in a huge variety of game genres.

The Limited Time Offer (LTO) module allows developers to configure a variety of offer bundles that can include virtual currencies, virtual items, and NFTs.

Key Benefits

: Define the ideal monetization strategy by testing various price points, trigger locations, durations, and item combinations.
Offer Scheduling: Set it and forget it. Months of offers can be prescheduled with individual start/end dates, price points, and item contents - all easily configured in a CSV.
Personalized Offers: PLAY's on-chain profile enables personalized LTOs based on player behaviour and preferences.
Segment Targeting: Create offers that automatically trigger for certain users, like creating a Starter Pack that only triggers for new users.
Server Control: Respond in real time to offer performance by enabling or disabling offers without the need to deploy an update.

Use Cases

Implementing a diverse range of offers with different price points, discounts, and durations facilitates the discovery of the most enticing offers for the player base. From bundles of discounted powerups in a match-3 game to a gun with a special skin in an FPS, the right sale at the right time can dramatically increase revenue.

PLAY's LTO Module enables the creation of all the expected offer styles needed for successful monetization, with added benefits and functionality enabled by Web3. Previous integrations have demonstrated that a limited-time offer featuring an NFT item can boost conversion rates by as much as 42%.

Starter Packs

Create a Starter Pack by configuring an LTO to exclusively target new users.

Starter Packs represent a prevalent monetization strategy across various games and can be a major driver for climbing the top-grossing charts when integrated with established games.

It's best to not put too much time pressure on a new player to purchase the Starter Pack - the most common time frame is around 7 days.

Cross-Game Items

Another approach involves offering LTOs containing rewards for multiple games.

For example, a player who frequently engages with two titles but has not yet made a purchase in either could receive an offer granting ad-free experiences or in-game currency for both titles - increasing the value proposition and likelihood of conversion.

Segment Targeting

PLAY's on-chain profile enables targeting LTOs to players across different games, based on their previous on-chain activity. This functionality facilitates triggering offers that the player is most likely to purchase, even if they have no purchase history in the game they are currently playing.

For instance, a player who previously made purchases at the $1.99 price point in Game A then transitions to Game B. Given their prior purchase history stored on-chain, an equivalently priced offer will trigger in Game B.

Additionally, LTOs can be utilized to encourage players to explore new titles aligned with their preferences.

For instance, a player in Action Game A who has been actively playing for over 14 days may be presented with an advertisement promoting Action Game B in PLAY's Dapp store, based on their preferences and retention in Action Game A.

NFT Passes

Benefits and Use Cases

Feature Overview

Battle/Season Passes are an integral monetization strategy today in many games, particularly multiplayer games. And for good reason - integrating a battle pass can provide dramatic lift to revenue generation, engagement, and retention.

Adding Web3 functionality on top of an already strong mechanic opens the door to creating even more innovative, fun experiences for players.

Key Benefits

Enhanced Monetization: Introduce a new revenue stream with NFT Battle/Season Passes that provide players with benefits, instant rewards, and access to limited-time game modes and events.
Cross-Game Integration: Web3 enables passes to unlock objectives and rewards across multiple titles - unlocking powerful promotion and UA strategies.
Segment Targeting: Create customized pass bundles and trigger them for the right players!
Flexibility: Want a battle pass? Done. Want a VIP Program? Also done. Configure the pass to suit your product goals.
Supercharged NFTs: Create a pass that can be recharged or topped up - enabling more customized durations and price points for players + innovative new monetization and retention strategies.
Upgradeable: Like a real-life loyalty card, an NFT pass can gain benefits as players spend. Reward your most engaged players who participate in multiple events/seasons with perks and bonuses.

Use Cases

There are nearly as many versions of passes as game genres - below are some examples of how the NFT Pass module can be leveraged in particular scenarios.

Subscription Pass

Create a rechargeable NFT pass to add a highly customized subscription feature that players engage with using in-game currency.

Cross-Game Pass

Another possible configuration is a game pass that leverages cross-game objectives, rewards, and segmented targeting - enabling unique promotional and UA benefits for games within a studio's portfolio.

For example, a studio has two hyper-casual titles - Game A and Game B. Game B has been launched with various improved features and monetization mechanics. The studio can strategically incentivize players from Game A to install and play Game B by creating a game pass with benefits and rewards in both games.

Players in Game A would be served a game pass offer that grants rewards in Game A for trying Game B, thereby driving installs and engagement in Game B and allowing the studio to gather valuable data in Game B without any UA spend.

Cross-game promotion via game passes is also a highly proven strategy employed by the largest publishing and platform gaming companies. PLAY's NFT Pass module unlocks this functionality for studios at any level in the ecosystem!

To increase conversion for the game pass offer, segment targeting allows for multiple price points and reward configurations to be triggered for players based on their prior play and spending patterns.

Offering custom price points and bundles based on a player's preferences is a proven method of enhancing monetization & driving engagement.

VIP Pass

PLAY's NFT Pass module allows a pass to function as a VIP/Loyalty program in addition to the core pass functionality.

VIP systems are commonly integrated into games to reward and retain spending players. As players spend, they unlock successive tiers of benefits based on the total amount they have spent in-game - incentivizing players to participate in each new season or event to improve the benefits they gain from their pass.

For example, making 5 purchases in-game could unlock a permanent 3% bonus when purchasing hard currency. Making 10 purchases could unlock access to a VIP room feature.

Another possible strategy would be rewarding players with a discounted or free pass for every 5th pass purchase (similar to a coffee shop loyalty card).

Combining typical pass mechanics with loyalty or VIP systems would increase a player's long-term investment into a game as their pass continuously increases in value the more they spend and play.

Unity

Unity integration

The primary functionality of the matchmaking module is to allow PvP matchmaking for synchronous gameplay.

Additional functionality referred to as "Voting" throughout this document allows for a matchmaking system wherein the winner is determined by votes cast by other players.

Therefor the Matchmaking module can be utilized for either PvP synchronous gameplay matches, or for the voting approach - the two styles do not have both be utilized.

Using the MatchmakingModule

Properties:

type (string): Identifies the match's type. Currently, only "default" is supported.
finishType (string): Describes how a match concludes, either through manual input or based on score submission.
startType (string): Outlines how a match commences, either manually or based on match filling.
maxUsers (int): Designates the maximum number of users permitted in the matchmaking process.
isStarted (bool): Indicates if the matchmaking process has been initiated.
votingEnabled (bool): Defines whether voting is permitted during the matchmaking process.
oncePerUserVoting (bool): Dictates whether a user can only vote once throughout the matchmaking process.
createdBy (string): The identifier of the user who initiated the matchmaking process. This value is updated by the backend.
updatedBy (string): The identifier of the user who last updated the matchmaking data. This value is updated by the backend.
createdAt (long): The timestamp denoting the creation time of the match. This value is updated by the backend.
updatedAt (long): The timestamp marking the most recent update of the matchmaking data. This value is updated by the backend.
participants (list of strings): Contains user identifiers of all participants involved in the matchmaking process.
votes (list of Vote objects): Stores the votes cast during the matchmaking process.
participantsScore: A dictionary that maps participant identifiers to their respective scores during the matchmaking process.
participantsPayload: A dictionary that maps participant identifiers to their respective optional payload data during the matchmaking process.

Lifecycle of a Match

Initially, all getter methods return empty lists, implying no current match.

Here's a step-by-step overview of a match's lifecycle:

A match is created with the settings provided via CreateMatchAsync(). By default, the user who created the match becomes a participant if participateInOnCreate is set to true.
GetJoinOpenMatchesAsync() returns the newly created match.
Other users join the match using ParticipateInMatchAsync().
Once the match fills up, it either begins automatically if matchFillBased is selected, or manually by invoking StartMatchAsync().
If votingEnabled is true, non-participating users can vote for participating users through VoteForMatchAsync(). To retrieve matches with voting enabled, use GetVoteOpenMatchesAsync().
If votingEnabled is false, participating users can submit their scores using SubmitMatchScoreAsync().
The match ends automatically if finishType is set to scoreSubmitBased once all users have submitted their scores, or it can be ended manually via FinishMatchAsync() in case the manual setting was submitted at the start.
The finished matches can be requested by calling the GetFinishedMatchesAsync() method.

Additional Features

The backend currently supports several features that the Unity SDK does not:

participateFee: An array of currencies. Users need to pay with these provided currencies to participate in the match.
voteFee: An array of currencies. Users need to pay with these provided currencies to vote for other users.
createMatchAchievements: A list of achievements with rewards given to the user who creates the match.
participateMatchAchievements: A list of achievements with rewards given to users who participate in the match.
startMatchAchievements: A list of achievements with rewards given to the user who starts the match.
voteForMatchAchievements: A list of achievements with rewards given to the user who votes for other users.
winnerMatchAchievements: A list of achievements with rewards given to users who win the match.
finishMatchAchievements: A list of achievements with rewards given to all users who participate in the match upon its conclusion.

Should you require any of the above features or have requests for additional features, please inform the PLAY team.

CreateMatchAsync

Description

The CreateMatchAsync method within the MatchmakingModule class is designed to asynchronously create a matchmaking match, based on the provided match configuration.

This method offers an asynchronous operation, returning a Task<MatchmakingData>, which represents the created match.

Parameters

MatchmakingData matchConfig: The configuration for the match to be created. This cannot be null.
bool participateInOnCreate: Optional parameter that determines whether the user participates in the match upon its creation. The default value is true.
Dictionary<string, object> participatePayload: Optional parameter that provides additional data for user participation. The default value is null.
CancellationToken cancellationToken: Optional parameter to enable the cancellation of the task. The default value is an unset CancellationToken.

Exceptions

ArgumentNullException: Thrown when matchConfig is null.
OperationCanceledException: Thrown when the operation is cancelled via the cancellationToken.

Example

Here's an example usage of the CreateMatchAsync method:

try
{
    // Create a match configuration
    MatchmakingData matchConfig = new MatchmakingData
    {
        // fill matchConfig details
    };

    // Create optional participation payload
    Dictionary<string, object> participatePayload = new Dictionary<string, object>
    {
        {"ExtraData1", "Value1"},
        {"ExtraData2", "Value2"}
    };

    // Call the CreateMatchAsync method
    var matchmakingResult = await MatchmakingModule.I.CreateMatchAsync(
        matchConfig,
        true,
        participatePayload);
}
catch (ArgumentNullException ex)
{
    Debug.Log("MatchConfig is null: " + ex.Message);
}
catch (OperationCanceledException ex)
{
    Debug.Log("Operation was cancelled: " + ex.Message);
}

Ensure to handle the possible exceptions for a smooth user experience. Always make sure matchConfig is not null before passing it to the method.

ParticipateInMatchAsync

Description

The ParticipateInMatchAsync method in the MatchmakingModule class allows a user to asynchronously participate in a matchmaking match, identified by the provided match ID.

The method performs an asynchronous operation, returning a Task<string> that signifies the ID of the match that the user has participated in.

Parameters

string matchId: The ID of the match to participate in. This value cannot be null or empty.
Dictionary<string, object> participantPayload: Optional parameter that provides additional data for user participation. The default value is null.
CancellationToken cancellationToken: Optional parameter to enable the cancellation of the task. The default value is an unset CancellationToken.

Exceptions

ArgumentNullException: Thrown when matchId is null or empty.
OperationCanceledException: Thrown when the operation is cancelled via the cancellationToken.

Example

Here's an example usage of the ParticipateInMatchAsync method:

try
{
    // Define the match ID
    string matchId = "your_match_id";

    // Create optional participant payload
    Dictionary<string, object> participantPayload = new Dictionary<string, object>
    {
        {"ExtraData1", "Value1"},
        {"ExtraData2", "Value2"}
    };

    // Call the ParticipateInMatchAsync method
    string participatedMatchId = await MatchmakingModule.I.ParticipateInMatchAsync(
        matchId,
        participantPayload);

    // Use the participatedMatchId in your game logic
    // ...
}
catch (ArgumentNullException ex)
{
    Debug.Log("MatchId is null or empty: " + ex.Message);
}
catch (OperationCanceledException ex)
{
    Debug.Log("Operation was cancelled: " + ex.Message);
}

Be sure to handle possible exceptions to ensure a seamless user experience. Always confirm that matchId is not null or empty before passing it to the method.

StartMatchAsync

Description

The StartMatchAsync method in the MatchmakingModule class allows for asynchronously starting a matchmaking match, identified by the provided match ID.

The method provides an asynchronous operation, returning a Task<string> that represents the ID of the match that has been started.

Parameters

string matchId: The ID of the match to start. This value cannot be null or empty.
CancellationToken cancellationToken: Optional parameter to enable the cancellation of the task. The default value is an unset CancellationToken.

Exceptions

ArgumentNullException: Thrown when matchId is null or empty.
OperationCanceledException: Thrown when the operation is cancelled via the cancellationToken.

Example

Here's an example usage of the StartMatchAsync method:

try
{
    // Define the match ID
    string matchId = "your_match_id";

    // Call the StartMatchAsync method
    string startedMatchId = await MatchmakingModule.I.StartMatchAsync(matchId);

    // Use the startedMatchId in your game logic
    // ...
}
catch (ArgumentNullException ex)
{
    Debug.Log("MatchId is null or empty: " + ex.Message);
}
catch (OperationCanceledException ex)
{
    Debug.Log("Operation was cancelled: " + ex.Message);
}

Always handle possible exceptions to ensure a seamless user experience. Make sure that matchId is not null or empty before passing it to the method.

VoteForMatchAsync

Description

The VoteForMatchAsync method in the MatchmakingModule class enables the casting of a vote asynchronously for a matchmaking match, identified by the provided match ID and participant ID.

The method conducts an asynchronous operation, returning a Task<string> that signifies the ID of the match for which the vote has been cast.

Parameters

string matchId: The ID of the match to vote for. This value cannot be null or empty.
string participantId: The ID of the participant casting the vote. This value cannot be null or empty.
CancellationToken cancellationToken: Optional parameter to enable the cancellation of the task. The default value is an unset CancellationToken.

Exceptions

ArgumentNullException: Thrown when matchId or participantId is null or empty.
OperationCanceledException: Thrown when the operation is cancelled via the cancellationToken.

Example

Here's an example usage of the VoteForMatchAsync method:

try
{
    // Define the match ID and participant ID
    string matchId = "your_match_id";
    string participantId = "your_participant_id";

    // Call the VoteForMatchAsync method
    string votedMatchId = await MatchmakingModule.I.VoteForMatchAsync(
        matchId,
        participantId);

    // Use the votedMatchId in your game logic
    // ...
}
catch (ArgumentNullException ex)
{
    Debug.Log("MatchId or ParticipantId is null or empty: " + ex.Message);
}
catch (OperationCanceledException ex)
{
    Debug.Log("Operation was cancelled: " + ex.Message);
}

Always handle possible exceptions to ensure a seamless user experience. Ensure both matchId and participantId are not null or empty before passing them to the method.

SubmitMatchScoreAsync

Description

The SubmitMatchScoreAsync method in the MatchmakingModule class enables a user to asynchronously submit the score for a matchmaking match, identified by the provided match ID.

The method provides an asynchronous operation, returning a Task<string> that signifies the ID of the match for which the score has been submitted.

Parameters

string matchId: The ID of the match for which the score is being submitted. This value cannot be null or empty.
long score: The score to be submitted for the match.
CancellationToken cancellationToken: Optional parameter to enable the cancellation of the task. The default value is an unset CancellationToken.

Exceptions

ArgumentNullException: Thrown when matchId is null or empty.
OperationCanceledException: Thrown when the operation is cancelled via the cancellationToken.

Example

Here's an example usage of the SubmitMatchScoreAsync method:

try
{
    // Define the match ID and score
    string matchId = "your_match_id";
    long score = 10000;  // your score

    // Call the SubmitMatchScoreAsync method
    string submittedScoreMatchId = await MatchmakingModule.I.SubmitMatchScoreAsync(
        matchId,
        score);

    // Use the submittedScoreMatchId in your game logic
    // ...
}
catch (ArgumentNullException ex)
{
    Debug.Log("MatchId is null or empty: " + ex.Message);
}
catch (OperationCanceledException ex)
{
    Debug.Log("Operation was cancelled: " + ex.Message);
}

Always handle possible exceptions to ensure a seamless user experience. Make sure matchId is not null or empty before passing it to the method.

FinishMatchAsync

Description

The FinishMatchAsync method in the MatchmakingModule class allows a user to asynchronously finish a matchmaking match, identified by the provided match ID.

The method executes an asynchronous operation, returning a Task<string> that represents the ID of the match that has been finished.

Parameters

string matchId: The ID of the match to finish. This value cannot be null or empty.
CancellationToken cancellationToken: Optional parameter to enable the cancellation of the task. The default value is an unset CancellationToken.

Exceptions

ArgumentNullException: Thrown when matchId is null or empty.
OperationCanceledException: Thrown when the operation is cancelled via the cancellationToken.

Example

Here's an example usage of the FinishMatchAsync method:

try
{
    // Define the match ID
    string matchId = "your_match_id";

    // Call the FinishMatchAsync method
    string finishedMatchId = await MatchmakingModule.I.FinishMatchAsync(matchId);

    // Use the finishedMatchId in your game logic
    // ...
}
catch (ArgumentNullException ex)
{
    Debug.Log("MatchId is null or empty: " + ex.Message);
}
catch (OperationCanceledException ex)
{
    Debug.Log("Operation was cancelled: " + ex.Message);
}

Always handle possible exceptions to ensure a seamless user experience. Confirm that matchId is not null or empty before passing it to the method.

GetJoinOpenMatchesAsync

Description

The GetJoinOpenMatchesAsync method in the MatchmakingModule class allows for asynchronously retrieving a list of open matches that a user can join.

The method executes an asynchronous operation, returning a Task<List<MatchmakingData>> that represents the list of open matches that the user can join.

Parameters

int limit: An integer indicating the maximum number of matches to retrieve.
string startAfter: An optional parameter representing a match ID after which to start retrieving the matches. The default value is an empty string.
CancellationToken cancellationToken: Optional parameter to enable the cancellation of the task. The default value is an unset CancellationToken.

Returns

Task<List<MatchmakingData>>: A task that represents the asynchronous operation. The task result contains a list of MatchmakingData objects, which are the open matches available for joining.

Example

Here's an example usage of the GetJoinOpenMatchesAsync method:

try
{
    // Define the limit and optionally the startAfter match ID
    int limit = 10;
    string startAfter = "some_match_id";  // Or leave empty for the default value

    // Call the GetJoinOpenMatchesAsync method
    List<MatchmakingData> openMatches =
        await MatchmakingModule.I.GetJoinOpenMatchesAsync(limit, startAfter);

    // Iterate over the openMatches and use in your game logic
    foreach (MatchmakingData match in openMatches)
    {
        // Your game logic here
        // ...
    }
}
catch (OperationCanceledException ex)
{
    Debug.Log("Operation was cancelled: " + ex.Message);
}

Always handle possible exceptions to ensure a seamless user experience. You can modify the limit and startAfter parameters to fit your application's specific needs.

GetVoteOpenMatchesAsync

Description

The method executes an asynchronous operation, returning a Task<List<MatchmakingData>> that represents the list of open matches that the user can vote on.

Parameters

int limit: An integer indicating the maximum number of matches to retrieve.
string startAfter: An optional parameter representing a match ID after which to start retrieving the matches. The default value is an empty string.
CancellationToken cancellationToken: Optional parameter to enable the cancellation of the task. The default value is an unset CancellationToken.

Returns

Task<List<MatchmakingData>>: A task that represents the asynchronous operation. The task result contains a list of MatchmakingData objects, which are the open matches available for voting.

Example

Here's an example usage of the GetVoteOpenMatchesAsync method:

try
{
    // Define the limit and optionally the startAfter match ID
    int limit = 10;
    string startAfter = "some_match_id";  // Or leave empty for the default value

    // Call the GetVoteOpenMatchesAsync method
    List<MatchmakingData> openVoteMatches = 
        await MatchmakingModule.I.GetVoteOpenMatchesAsync(limit, startAfter);

    // Iterate over the openVoteMatches and use in your game logic
    foreach (MatchmakingData match in openVoteMatches)
    {
        // Your game logic here
        // ...
    }
}
catch (OperationCanceledException ex)
{
    Debug.Log("Operation was cancelled: " + ex.Message);
}

Always handle possible exceptions to ensure a seamless user experience. You can modify the limit and startAfter parameters to fit your application's specific needs.

GetFinishedMatchesAsync

Description

The GetFinishedMatchesAsync method in the MatchmakingModule class allows for asynchronously retrieving a list of finished matches.

The method executes an asynchronous operation, returning a Task<List<MatchmakingData>> that represents the list of finished matches.

Parameters

int limit: An integer indicating the maximum number of matches to retrieve.
string startAfter: An optional parameter representing a match ID after which to start retrieving the matches. The default value is an empty string.
CancellationToken cancellationToken: Optional parameter to enable the cancellation of the task. The default value is an unset CancellationToken.

Returns

Task<List<MatchmakingData>>: A task that represents the asynchronous operation. The task result contains a list of MatchmakingData objects, which are the finished matches for the current app.

Example

Here's an example usage of the GetFinishedMatchesAsync method:

try
{
    // Define the limit and optionally the startAfter match ID
    int limit = 10;
    string startAfter = "some_match_id";  // Or leave empty for the default value

    // Call the GetFinishedMatchesAsync method
    List<MatchmakingData> finishedMatches =
        await MatchmakingModule.I.GetFinishedMatchesAsync(limit, startAfter);

    // Iterate over the finishedMatches and use in your game logic
    foreach (MatchmakingData match in finishedMatches)
    {
        // Your game logic here
        // ...
    }
}
catch (OperationCanceledException ex)
{
    Debug.Log("Operation was cancelled: " + ex.Message);
}

Always handle possible exceptions to ensure a seamless user experience. You can modify the limit and startAfter parameters to fit your application's specific needs.

GetFinishedMatchByIdAsync

Description

The method executes an asynchronous operation, returning a Task<MatchmakingData> that represents the data of the finished match.

Parameters

string matchId: The ID of the finished match.
CancellationToken cancellationToken: Optional parameter to enable the cancellation of the task. The default value is an unset CancellationToken.

Returns

Task<MatchmakingData>: A task that represents the asynchronous operation. The task result contains the MatchmakingData of the finished match.

Example

Here's an example usage of the GetFinishedMatchByIdAsync method:

try
{
    // Define the match ID
    string matchId = "some_match_id";

    // Call the GetFinishedMatchByIdAsync method
    MatchmakingData finishedMatch =
        await MatchmakingModule.I.GetFinishedMatchByIdAsync(matchId);

    // Use the finishedMatch in your game logic
    // ...
}
catch (OperationCanceledException ex)
{
    Debug.Log("Operation was cancelled: " + ex.Message);
}
catch (Exception ex)
{
    Debug.Log("Failed to get the match: " + ex.Message);
}

Always handle possible exceptions to ensure a seamless user experience. You can modify the matchId parameter to retrieve the data of any specific finished match by its ID.