Achievement.md

PICO VR Achievement Integration Guide

This guide will walk you through the process of integrating achievements into your PICO VR application using the Achievement Manager. Achievements add a layer of engagement and motivation for users to explore and enjoy your VR experience.

Table of Contents

• Overview
• Get Achievement data
  • Get Achievement Information
  • Get Achievement Information
  • Get Basic Information of Achievements on a Page
• Update Achievement Progress
  • Unlock a Simple Achievement
  • Update Progress for a Count Achievement
  • Update Progress for a Bitfield Achievement

Overview

The Achievement Manager is a tool for managing and tracking achievements in your PICO VR application. It provides a way to integrate achievements, display them in your user interface, and interact with the PICO VR achievement API.

Get Achievement data

Get Achievement Information

Retrieve information about achievements, including their API name, description, type, and unlock criteria.

AchievementsService.GetDefinitionsByName(new string[] { "yourAchievementName" }).OnComplete(
    (msg) => { // Message<AchievementDefinitionList>
        if (!msg.IsError)
        {
            var list = msg.Data.GetEnumerator();
            while (list.MoveNext())
            {
                var item = list.Current;
                Debug.Log($"Name: {item.Name}" +
                          $"Target: {item.Target}" +
                          $"Type: {item.Type}" +
                          $"BitfieldLength: {item.BitfieldLength}" +
                          $"Description: {item.Description}" +
                          $"Title: {item.Title}" +
                          $"IsArchived: {item.IsArchived}" +
                          $"IsSecret: {item.IsSecret}" +
                          $"ID: {item.ID}" +
                          $"UnlockedDescription: {item.UnlockedDescription}" +
                          $"WritePolicy: {item.WritePolicy}" +
                          $"LockedImageURL: {item.LockedImageURL}" +
                          $"UnlockedImageURL: {item.UnlockedImageURL}");
            }
        }
    }
);

Get Basic Information of Achievements on a Page

To retrieve basic information about achievements on a specified page:

AchievementsService.GetAllDefinitions(0, 5).OnComplete(
    (msg) => { // Message<AchievementDefinitionList>
        if (!msg.IsError)
        {
            var list = msg.Data.GetEnumerator();
            var totalSize = msg.Data.TotalSize; // The total number of achievements
            while (list.MoveNext())
            {
                var item = list.Current;
                Debug.Log($"Name: {item.Name}" +
                          $"Target: {item.Target}" +
                          $"Type: {item.Type}" +
                          $"BitfieldLength: {item.BitfieldLength}" +
                          $"Description: {item.Description}" +
                          $"Title: {item.Title}" +
                          $"IsArchived: {item.IsArchived}" +
                          $"IsSecret: {item.IsSecret}" +
                          $"ID: {item.ID}" +
                          $"UnlockedDescription: {item.UnlockedDescription}" +
                          $"WritePolicy: {item.WritePolicy}" +
                          $"LockedImageURL: {item.LockedImageURL}" +
                          $"UnlockedImageURL: {item.UnlockedImageURL}");
            }
        }
    }
);

Get Achievement Progress

Retrieve the progress a user has made on a specific achievement, including whether it's unlocked, the unlock time, and more.

AchievementsService.GetProgressByName(new string[] { "yourAchievementName" }).OnComplete(
    (msg) => { // Message<AchievementProgressList>
        var list = obj.GetEnumerator();
        while (list.MoveNext())
        {
            var item = list.Current;
            Debug.Log($"IsUnlocked: {item.IsUnlocked}" + // Simple achievements have no progress information and they only have two statuses: locked, unlocked.
                      $"UnlockTime: {item.UnlockTime}" +
                      $"ID: {item.ID}" +
                      $"Name: {item.Name}" +
                      $"Bitfield: {item.Bitfield}" + // The progress of a bitfield achievement
                      $"Count: {item.Count}" + // The progress of a count achievement
                      $"ExtraData: {Encoding.UTF8.GetString(item.ExtraData)}");
        }
    }
);

Update Achievement Progress

Unlock a Simple Achievement

Unlock an achievement when a user reaches the specified goal:

AchievementManager.Instance.UnlockAchievement("Achievement_Name");

Update Progress for a Count Achievement

For count-based achievements, use the AddCount method:

Copy code
int count = 1;
byte[] bytes = new byte[] { };
AchievementsService.AddCount("yourAchievementName", count, bytes).OnComplete(
    (msg) => { // msg:Message<AchievementUpdate>
        if (!msg.IsError)
        {
            var updateData = msg.Data;
            Debug.Log($"achievementName: {updateData.Name}");
            Debug.Log($"JustUnlocked: {updateData.JustUnlocked}");
        }
    }
);

Update Progress for a Bitfield Achievement

For bitfield-based achievements, use the AddFields method:

Copy code
byte[] bytes = new byte[] { };
string fields = "100011";
AchievementsService.AddFields("yourAchievementName", fields, bytes).OnComplete(
    (msg) => { // msg:Message<AchievementUpdate>
        if (!msg.IsError)
        {
            var updateData = msg.Data;
            Debug.Log($"achievementName: {updateData.Name}");
            Debug.Log($"JustUnlocked: {updateData.JustUnlocked}");
        }
    }
);