Going Social: Leaderboards

Oculus Developer Blog
Posted by Oculus VR
July 5, 2018

Welcome to the second blog in our going social series: incorporating a leaderboard into your application.

Whether you already have an application published on the Oculus Store or you are designing your first VR experience, the Oculus Platform SDK provides a variety of social features and services that will help make your app socially relevant.

As a developer, your ability to effectively scope out new content and provide added value is dependent in large part on cultivating and maintaining a user base that will want to continually revisit your application. Consider the users that provide public reviews of your application on the Oculus Store to be just like the test users your application depended on as it went through our release channels: a source of actionable feedback that help your application continue to evolve and grow.

Applications that incorporate social features can appeal to a wider audience by offering the potential for a community to form around them. Depending on the type of application you are designing, Oculus offers a variety of services and features that may align with your goals. Whether it be monetization, spreading awareness, or bringing together users in new and exciting ways with our rooms and matchmaking integration, our Platform SDK has you covered.

In this blog we will walk you through integrating a basic leaderboard into your Unity application on the Oculus Store.

Going Social Is Easier Than You Think

Adding a social component to your application can be as simple as adding a leaderboard. Leaderboards offer your users outlets to compare and contrast their unique experiences within your application and can be an important part of creating a sense of community.

You may remember the original leaderboard: pinball and arcade machines are prime examples of using it effectively. The end goal of incorporating a leaderboard into your application is to keep your users coming back with the intent of surpassing their previous score or higher ranking players. When coupled with challenging and engaging content this can form a community of passionate users.

The ability to visually represent a player's progress in your application by using a leaderboard is a great way to drive engagement within your application. Whether your app is single-player or multiplayer, a leaderboard can be a great social feature to offer.

How To Implement a Leaderboard in Your Unity Project

To demonstrate the proper format for adding a leaderboard to your project, we will walk through setting up the initial coding framework for a basic tallying leaderboard. A tallying leaderboard reports the best score for a user of your application in accordance with the variables you set in your code. This example is partly based on the sample Unity project VR Hoops, which is included in our Platform SDK package located on the developer download page.

To use our sample projects, you will need to extract the Platform SDK and navigate to /Samples/Unity/[sample name] project folder location and open that folder from within the Unity launcher.

Once you have created or opened up a sample project in Unity, you will need to perform the following two steps to enable our platform functionality:

1) Import the Oculus Platform unity package to provide our platform integration support.

2) Add your application ID from your developer dashboard to Unity's OculusPlatformSettings menu.

As described in the documentation, prior to adding a custom leaderboard to your application you must first create and define the API name and sort order of the leaderboard for your app in your developer dashboard. The sort order is a method of displaying your user's high scores in either ascending or descending order and is dependent on the type of game or experience you are designing. For instance, a golf game might want the “lower is better” option as scoring in golf is defined by the lowest score being best.

For the purpose of our example, we are calling this leaderboard “Most Gophers Caught” and arranging the leaderboard from high to low score by setting the sort order to “Higher is Better”.

The example code provided for VR Hoops is on the higher level of leaderboard functionality, as it offers competitive matchmaking with up to three players, a timer to reset each round once a set amount of points has been hit, and a cumulative score board to display the most wins and highest scores.

In this simplified leaderboard implementation script, we are only looking to demonstrate basic tallying functionality (how many gophers are caught in one game) in a single player application. The following example code sets up the format for this type of leaderboard:

  using UnityEngine;
  using System.Collections.Generic;
  using Oculus.Platform;
  using Oculus.Platform.Models;
  // Coordinates updating leaderboard scores and polling for leaderboard updates.
  public class LeaderboardManager
      // API NAME for the leaderboard where we store how many matches the user has won
      private const string MOST_GOPHERS_CAUGHT = "MOST_GOPHERS_CAUGHT";
      // the top number of entries to query
      private const int TOP_N_COUNT = 3;
      // how often to poll the service for leaderboard updates
      private const float LEADERBOARD_POLL_FREQ = 30.0f;
      // the next time to check for leaderboard updates
      private float m_nextCheckTime;
      // whether we've found the local user's entry yet
      private bool m_foundLocalUserMostWinsEntry;
      // number of times the local user has won
      private long m_numWins;
      // callback to deliver the most-wins leaderboard entries
    private OnMostWinsLeaderboardUpdated m_mostWinsCallback;

When deciding how best to display the leaderboard in your application, consider the new user experience first and choose a display that makes sense for a first time user of your application that is both intuitive and useful.

For example, if your application happened to be a first-person shooter experience you may want to enable a toggle-able, head-locked quad layer using the OVROverlay script provided in our Unity Utilities package. This would allow the player to bring up their local leaderboard whenever they chose to, providing a useful on-demand interaction within your application.

You may also choose to make your leaderboard static (as in the VR Hoops sample we provide and which is pictured above) if your application was to be a seated experience or the user is to be confined to one set area for the duration of your application. Such leaderboards make use of a simple canvas backdrop in Unity and function as handy display boards letting the user known where they stand at a glance.

However you choose to implement a leaderboard in your application is up to you---but we highly recommend evaluating other leaderboard integrations in applications that are similar to yours to see what has worked best for other developers of similar content previously.

Want to know more about our social platform features?

Please feel free to explore the rest of our moderate to advanced features in our Platform SDK documentation's developer guide! We offer sixteen different social implementations that can add varying amounts of depth and immersion to your application from matchmaking players that want to compete head-to-head in your app, to additional methods of communication that can be offered via our Voice Chat (VOIP) integration.