Asset Instance Progressions

Asset instance progressions are progressions that track the progressions of Assets.

Starting an Asset instance on a progression is as easy as just starting to add points to it. That progression will then be listed when retrieving progressions for that Asset.

Retrieving Asset instance progressions

Retrieving a single Asset instance progression using the progression key

int assetInstanceId = 1;
string progressionKey = "mage";

LootLockerSDKManager.GetAssetInstanceProgression(assetInstanceId, progressionKey, response =>
{
    if (!response.success) {
        Debug.Log("Failed: " + response.Error);
    }
    
    // Output the asset instance level and show how much points are needed to progress to the next tier
    Debug.Log($"The asset instance is currently level {response.step}");
    if (response.next_threshold != null)
    {
        Debug.Log($"Points needed to reach next level: {response.next_threshold - response.points}");
    }
});

Retrieving all Asset instance progressions

int assetInstanceId = 1;

LootLockerSDKManager.GetAssetInstanceProgressions(assetInstanceId, response =>
{
    if (!response.success) {
        Debug.Log("Failed: " + response.Error);
    }

    // Output the asset instance level and show how much points are needed to progress to the next tier for all asset instance progressions
    foreach (var assetInstanceProgression in response.items)
    {
        Debug.Log($"Current level in {assetInstanceProgression.progression_name} is {assetInstanceProgression.step}");
        if (assetInstanceProgression.next_threshold != null)
        {
            Debug.Log($"Points needed to reach next level in {assetInstanceProgression.progression_name}: {assetInstanceProgression.next_threshold - assetInstanceProgression.points}");
        }
    }
});

Retrieving Asset instance progressions using count

Count can be used to limit the number of entries returned.

int assetInstanceId = 1;
int count = 20;

LootLockerSDKManager.GetAssetInstanceProgressions(assetInstanceId, count, response =>
{
    if (!response.success) {
        Debug.Log("Failed: " + response.Error);
    }

    // Output the asset instance level and show how much points are needed to progress to the next tier for all asset instance progressions
    foreach (var assetInstanceProgression in response.items)
    {
        Debug.Log($"Current level in {assetInstanceProgression.progression_name} is {assetInstanceProgression.step}");
        if (assetInstanceProgression.next_threshold != null)
        {
            Debug.Log($"Points needed to reach next level in {assetInstanceProgression.progression_name}: {assetInstanceProgression.next_threshold - assetInstanceProgression.points}");
        }
    }
});

Paginating through Asset instance progressions

You can use "after" parameter to paginate if the Asset instance is on many progressions.

int assetInstanceId = 1;
int numberOfItemsPerPage = 10;
LootLockerPaginatedAssetInstanceProgressionsResponse assetInstanceProgressions;

void Start()
{
    LootLockerSDKManager.StartGuestSession(_ =>
    {
        // Fetch the initial asset instance progressions list
        LootLockerSDKManager.GetAssetInstanceProgressions(assetInstanceId, numberOfItemsPerPage, response =>
        {
            if (!response.success)
            {
                Debug.Log("Failed: " + response.Error);
            }

            if (response.pagination.total == 0)
            {
                Debug.Log("Your asset instance does not have any progressions, start them by giving it some exp");
            }

            assetInstanceProgressions = response;
        });
    });
}

void Update()
{
    if (assetInstanceProgressions == null) return;

    // Fetch the next page if more asset instance progressions exist
    if (Input.GetKeyDown(KeyCode.RightArrow) && assetInstanceProgressions.pagination.next_cursor != null)
    {
        LootLockerSDKManager.GetAssetInstanceProgressions(assetInstanceId, numberOfItemsPerPage, assetInstanceProgressions.pagination.next_cursor, response =>
        {
            if (!response.success)
            {
                Debug.Log("Failed: " + response.Error);
            }
            
            assetInstanceProgressions = response;
            Debug.Log($"Paginating right, got {assetInstanceProgressions.items.Count} progressions");
        });
    }
    
    // Fetch the previous page if we are not on the first page
    if (Input.GetKeyDown(KeyCode.LeftArrow) && assetInstanceProgressions.pagination.previous_cursor != null)
    {
        LootLockerSDKManager.GetAssetInstanceProgressions(assetInstanceId, numberOfItemsPerPage, assetInstanceProgressions.pagination.previous_cursor, response =>
        {
            if (!response.success)
            {
                Debug.Log("Failed: " + response.Error);
            }

            assetInstanceProgressions = response;
            Debug.Log($"Paginating left, got {assetInstanceProgressions.items.Count} progressions");
        });
    }
}

Above is an example of how to implement retrieval of multiple asset instance progressions supplying a count to limit the number of progressions to receive and supplying a cursor into the after parameter to paginate using blueprints in Unreal Engine.

Input

You need to exchange the trigger with an event that you want to trigger the flow. For example a button click or level start.

You also need to supply the id of the asset instance for which you want to retrieve the progression from.

To use pagination you should supply a value to the after parameter and optionally a value to the count parameter. For an explanation, see below.

Output

We recommend branching the completed event on the success flag, and if you do this you will probably want to add error handling in case the request fails.

The response contains a list of progressions. The returned progressions contain the needed information on each progression that you may want to use for display or flow control.

The response also contains pagination data which you use as follows.

Usage example

Understanding pagination for the first time can be a challenge. So an example can help.

Say you have 50 progressions to receive. You can do this with pagination like this:

Trigger the GetInstanceProgressions node with a count parameter of 10.
1. Use the 10 progression items returned as you want (for example display in the UI). Note that out of your 50 progressions, these are progressions 1-10.
2. Save the returned pagination data to make the next request. The most important here is the "Next Cursor" property. This is the value that you need to submit to subsequent GetInstanceProgressions calls to "offset" the call to start at the next progression item after the ones you've already received.
Trigger the GetInstanceProgressions node again with a count of 10 but now also input the value "Next Cursor" into the after parameter. This tells the node to start off where it finished last time.
1. Use the 10 new progression items returned as you want. Note that this time it is progressions 11-20 of your 50 progressions.
2. Again, save the returned pagination data so that you can make subsequent requests.
Repeat step 2 with new values for "Next Cursor" until you have received all the progressions.

This is how you paginate. It may seem redundant in this example because you could just set Count to 50 and get everything at once. But imagine you have thousands of progressions with rewards of all kinds. Then this system is very valuable.

Interacting with Asset instance progressions

Adding points to an Asset instance progression

int assetInstanceId = 1;
string progressionKey = "mage";
ulong amountOfPoints = 100;

LootLockerSDKManager.AddPointsToAssetInstanceProgression(assetInstanceId, progressionKey, amountOfPoints, response =>
{
    if (!response.success) {
        Debug.Log("Failed: " + response.Error);
    }

    // If the awarded_tiers array contains any items that means the asset instance leveled up
    // There can also be multiple level-ups at once
    if (response.awarded_tiers.Any())
    {
        foreach (var awardedTier in response.awarded_tiers)
        {
            Debug.Log($"Reached level {awardedTier.step}!");

            foreach (var assetReward in awardedTier.rewards.asset_rewards)
            {
                Debug.Log($"Rewarded with an asset, id: {assetReward.asset_id}!");
            }
            
            foreach (var progressionPointsReward in awardedTier.rewards.progression_points_rewards)
            {
                Debug.Log($"Rewarded with {progressionPointsReward.amount} bonus points in {progressionPointsReward.progression_name} progression!");
            }
            
            foreach (var progressionResetReward in awardedTier.rewards.progression_reset_rewards)
            {
                Debug.Log($"Progression {progressionResetReward.progression_name} has been reset as a reward!");
            }
        }
    }
});

Subtracting points from an asset instance progression

int assetInstanceId = 1;
string progressionKey = "mage";
ulong amountOfPoints = 10;

LootLockerSDKManager.SubtractPointsFromAssetInstanceProgression(assetInstanceId, progressionKey, amountOfPoints, response =>
{
    if (!response.success) {
        Debug.Log("Failed: " + response.Error);
    }
    
    // Output the amount of points the asset instance has after subtracting points
    Debug.Log($"Asset instance now has {response.points} points in {response.progression_name} progression");
});

Resetting an asset instance progression

Resets the asset instance progression points to 0, effectively returning the asset instance to level 1, if you want to remove the progression from a asset instance see below.

int assetInstanceId = 1;
string progressionKey = "mage";

LootLockerSDKManager.ResetAssetInstanceProgression(assetInstanceId, progressionKey, response =>
{
    if (!response.success) {
        Debug.Log("Failed: " + response.Error);
    }
    
    // Asset instance level is now 1 
    Debug.Log($"Asset instance is level {response.step} since the {response.progression_name} was reset");
});

Deleting an asset instance progression

Completely removes an asset instance progression, it will no longer be listed when retrieving asset instance progressions.

int assetInstanceId = 1;
string progressionKey = "mage";

LootLockerSDKManager.DeleteAssetInstanceProgression(assetInstanceId, progressionKey, response =>
{
    if (!response.success) {
        Debug.Log("Failed: " + response.Error);
    }
    
    // Trying to fetch the deleted asset instance progression will result in a "Not Found" error
    LootLockerSDKManager.GetAssetInstanceProgression(progressionKey, response =>
    {
        if (!response.success) {
            Debug.Log("Failed: " + response.Error);
        }
    }
});

PreviousClass Progressions NextTriggers

Last updated 1 year ago