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 SDK requires the following software:

• Unity 2020 LTS or later. Installation instructions.

  • 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:

1. Open project settings Unity window: Edit->Project Settings...

2. Select Player and open the Other Settings section

3. For iOS tab change the Bundle Identifier

4. For Android tab change the Package Name

Android

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

For Android you can also change the Scripting Backend from Mono to IL2CPP. Since Unity Android Mono backend does not support arm64 which is required on Android Play Market. But to keep the development iterations faster, you can also keep Mono and only later jump to IL2CPP.

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:

• Creating a GitHub issue here

• Dropping a message in our Discord dev-chat here

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:

1. 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.

Structure

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

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:

1. Go on the developer dashboard and select your project.

1. Click on Download unity packages to download your project credentials.

1. Go on the and select/create your project.

1. 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.

1. Open your level blueprint.

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

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

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.

Guest login

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.

Email login

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.

Guest Login/Logout

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

Subscribe Authentication Changed event

Email Login/Logout

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.

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.

Introduction

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

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

using RGN;
using RGN.Modules.UserProfile;
using UnityEngine;

public class UserProfileExample : MonoBehaviour
{
    public async void LoadUserProfileDataAsync()
    {
        string userId = RGNCore.I.MasterAppUser.UserId;
        UserProfileData userProfileData = await UserProfileModule.I.GetFullUserProfileAsync<UserProfileData>();
        Debug.Log($"Display name : {userProfileData.displayName} \n" +
            $"Bio : {userProfileData.bio} \n" +
            $"Email : {userProfileData.email} \n");
    }
}

Update UserName/Display Name

using UnityEngine;
using RGN.Modules.UserProfile;

public class UserProfileExamples : MonoBehaviour
{
    private async void UpdateDisplayName()
    {
        string newDisplayName = await UserProfileModule.I.SetDisplayNameAsync("New display name");
        Debug.Log($"Display name : {newDisplayName}");
    }
}

Update User Bio

using UnityEngine;
using RGN.Modules.UserProfile;

public class UserProfileExamples : MonoBehaviour
{
    private async void UpdateUserBio()
    {
        string newBio = await UserProfileModule.I.SetBioAsync("This is my user description");
        Debug.Log($"Bio : {newBio}");
    }
}

Retrieve User Currencies

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

public class UserProfileExamples : MonoBehaviour
{
    private async void GetUserCurrencies()
    {
        List<Currency> currencies = await UserProfileModule.I.GetUserCurrenciesAsync();
        foreach (Currency currency in currencies)
        {
            Debug.Log($"Type : {currency.name} Quantity : {currency.quantity}");
        }
    }
}

"rgn-coin" Currency

Similar to other in-game currencies but it can only be obtained by making In-App Purchases - it cannot be earned or given as a reward to players. It is consumed to purchase NFT #virtual-items. For more details about the rgn-coin, please refer to the Currency module.

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 added using the PLAY Dev Dashboard. In order to retrieve your list of virtual items you can use the following API.

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.

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

Introduction

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

Get User Profile

Update UserName/Display Name

Update User Bio

Get User Currencies

"rgn-coin" Currency

Similar to other in-game currencies but it can only be obtained by making In-App Purchases - it cannot be earned or given as a reward to players. It is consumed to purchase NFT #virtual-items. For more details about the rgn-coin, please refer to the Currency module.

Developers have access to two different environments:

1. Staging: Use this environment while developing and testing. This environment will use the testing blockchain backend.

2. Production: Use this environment for the releases, live versions available to users.

Example.

1. John started integrating the READYgg SDK in his application by setting the Staging environment.

2. He completed and tested feature Implementation in the Staging environment.

3. 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.

4. 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

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.

Get Store Offers

Buy Virtual Items and Store offers

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.

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:

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.

Get game achievements

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

public class AchievementExamples : MonoBehaviour
{
    private async void GetAllGameAchievements()
    {
        // Retrieves the 10 first achievements setup for my game
        List<AchievementData> achievements = await AchievementsModule.I.GetForCurrentAppAsync(10);
        foreach (var achievement in achievements)
        {
            Debug.Log($"Achievement name : {achievement.name} \n" +
                $"Description : {achievement.description}");
        }
    }
}

Get user achievements

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

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

public class AchievementExamples : MonoBehaviour
{
    private async void GetUserAchievementsAsync()
    {
        List<AchievementWithUserData> achievements = await AchievementsModule.I.GetForCurrentAppWithUserDataAsync(10);
        foreach (var achievement in achievements)
        {
            UserAchievement userAchievement = achievement.GetUserAchievement();
            Debug.Log($"Achievement name : {achievement.name} \n" +
                $"Achievement progression : {userAchievement.value}/{achievement.valueToReach}");
        }
    }
}

Trigger achievement by id

using UnityEngine;
using RGN.Modules.Achievement;

public class AchievementExamples : MonoBehaviour
{
    private async void CompleteAchievementAsync()
    {
        await AchievementsModule.I.TriggerByIdAsync("myAchievementId");
        // This will increase the achievement progression by 1
        // An additionnal parameter can be passed to increase the progress amount
    }
}

Trigger achievement by request name

The request name can be set in the developer dashboard when creating the achievement.

using UnityEngine;
using RGN.Modules.Achievement;

public class AchievementExamples : MonoBehaviour
{
    private async void CompleteAchievementAsync()
    {
        await AchievementsModule.I.TriggerByRequestNameAsync("myRequestName");
        // This will increase the achievement progression by 1
        // An additionnal parameter can be passed to increase the progress amount
    }
}

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.

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

public class AchievementExamples : MonoBehaviour
{
    private async void ClaimAchievementAsync()
    {
        var result = await AchievementsModule.I.ClaimByIdAsync("achievementId");
        List<AchievementReward> rewards = result.rewards;
        foreach (var reward in rewards)
        {
            Debug.Log($"Reward name : {reward.name} \n" +
                $"Reward type : {reward.type} \n" +
                $"Reward quantity : {reward.quantity}");
        }
    }
}

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.

The request name can be set in the developer dashboard when creating the achievement.

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

public class AchievementExamples : MonoBehaviour
{
    private async void ClaimAchievementAsync()
    {
        var result = await AchievementsModule.I.ClaimByRequestNameAsync("myRequestName");
        List<AchievementReward> rewards = result.rewards;
        foreach (var reward in rewards)
        {
            Debug.Log($"Reward name : {reward.name} \n" +
                $"Reward type : {reward.type} \n" +
                $"Reward quantity : {reward.quantity}");
        }
    }
}

Coming soon

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:

1. Virtual Items rewards - the virtual items are added to the user's inventory

2. 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.

3. 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:GetUserProgressionDataAsync() method.

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

Developers have access to two different environments:

1. Staging: Use this environment while developing and testing. This environment will use the testing blockchain backend.

2. Production: Use this environment for the releases, live versions available to users.

Example.

1. John started integrating the PLAY SDK in his application by setting the Staging environment.

2. He completed and tested feature Implementation in the Staging environment.

3. 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.

4. 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

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 .

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.

Get user rgn-coin quantity

Add rgn-coin to user

Custom currency

Get user custom currency quantity

Add custom currency to user

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:

Get Custom User Data

You can get your custom serialized classes in our database:

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.

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.

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

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

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

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

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

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

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

"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");
    }
}

Package Dependencies Installation:

1. Follow the link - https://github.com/readyio/rgn_unreal and clone it somewhere nearby the project directory.

2. Open the just pulled repository and copy the folder “Plugins” from it to the root of your project directory.

3. Open your project via Unreal Engine again and accept the offer to rebuild the modules.

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

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.

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.