Leaderboards are an essential component for multiplayer games because leaderboards invoke more competition. Competition builds with comparison and gamers want to see how they stack up against other players. Leaderboards improve engagement because gamers are motivated to improve their scores and will keep playing your game until they do. Players motivated by real-time global scoreboards will have longer play times and bring players back to the game to try and obtain better scores.
Online Unity Games Need Online Features
Unity games that are connected online need social features such as in-game chat for players to communicate with players and teammates, friendly competitions with live leaderboard updates and scores, and notifications to update players on missed messages, in-game events, and news about the game. While developers can set up this online infrastructure themselves, online features take time, money, and resources to create, secure, maintain, and update constantly. The resources used in this endeavor could be used instead to add more features to the game itself.
PubNub and Unity Game streaming abilities
This is where PubNub, a developer API platform that enables applications to receive real-time updates at a massive, global scale, can handle this online functionality infrastructure. PubNub serves as the foundation for over 2000 customers in diverse industries, including gaming. Game developers can depend on PubNub’s scalability and reliability to power their games and tools for in-game chat, live leaderboard updates, and alerts and notifications to bring players back to the game.
In this Unity tutorial, you'll learn how to create leaderboards that update in real time when a new score is submitted using PubNub. You'll be able to enter usernames and scores as the score values and watch them update from other players in real time. With the PubNub Unity SDK, you’re able to create real-time games and experiences with ease. Although this tutorial guides you through the process step-by-step, you can watch a video walkthrough of this tutorial on YouTube, as well as view the finished project in the GitHub repository.
Note: This post was written using an older version of Unity (2018 LTS version) and PubNub's Unity SDK.
Want to learn more?
Fill out the form and one of our experts will be in touch soon
Creating a Unity Leaderboard Environment
Before you begin, you’ll need to download the Unity Hub. The Unity Hub is used to manage Unity 2D and Unity 3D projects you’re developing.
Once you’ve downloaded Unity Hub, add any Unity Editor Version equal to or older than 2018 LTS, as the 2018 LTS version was used to create the real-time leaderboard demo application.
Unity Gaming leaderboard system setup
Download or clone the Real-Time Unity High Score Leaderboards repo. Open Unity Hub, go to the projects tap, and click ‘Add’.
If you’re using a Unity version newer than 2018 LTS, then you’ll be asked to confirm you want to upgrade the project to a newer version of Unity. Click ‘Confirm’ to continue.
When you import the project you may get error messages in the Unity Console. This will be handled in the next step.
Fixing the ‘TestTools does not exist’ errors in Unity
After importing the PubNub SDK or the tutorial project, you might see an error message in the Unity console window that looks like this:
error CS0234: The type or namespace name 'TestTools' does not exist…
Fix the error by going to Window > General > Test Runner. Click on the drop-down menu in the top right corner and Enable playmode tests for all assemblies. Close all open Unity windows completely and reopen your project.
Open up the Assets folder in your Project tab, and double-click on the LeaderBoard Unity Scene.
When you click on the LeaderBoard scene, you should see this:
To try out the demo, click the 'Play' button at the top of the Unity Editor.
If you receive the following error:
Scene ‘LeaderBoard’ couldn’t be loaded because it has not been added to the build settings or the AssetBundle has not been loaded.
Follow the steps below:
To fix this, go to File > Build Settings. Click the ‘Add Open Scenes’ button. Then go back to your Project tab, and double-click on the ‘LeaderBoard’ scene. Go back to your Build Settings, and click ‘Add Open Scenes’ once again. Then, in your Project Tab, double-click on the LeaderBoard scene again and run the project.
PubNub Keys & Functions Setup for Unity Leaderboard systems
Before you can see the leaderboard demo running properly, you’ll need free API keys from PubNub to continue. To get these keys:
Sign up for a PubNub account.
Go to your PubNub Dashboard.
Click Create New App and give your app a name.
Click Create.
Click your new app to open its settings, then click its keyset.
Enable Message Persistence. This is required to remember your scores as well as to sort them in real time.
Save the changes.
Copy the Publish and Subscribe keys to a text editor for the next steps.
Next, you need to set up a Function to sort scores and publish the list to the ‘leaderboard_scores’ channel. To make a Function, navigate back to your application in the PubNub Admin Dashboard.
On the left-hand side, click the Functions button.
Create a new Module.
Create a new Function by giving the function a name and ensure the Event selected is After Publish or Fire. Make sure you are listening to the correct channel name, in this case, the score submission channel is “submit_score”.
In the function, you have to import the KV Store and PubNub dependencies. You'll parse the message JSON received from the Unity leaderboard client and place the contents of the message into variables called username and score.
You will use db.get to check if there is any data stored in the KV store. If there isn’t, db.set is used to create a string format of how the data will be structured. Once the data is in the KV store, iterate through the point values array using value.score.some(item => {});. Use the prototype for the score variables, since you want to be able to return true at the end of the loop to cancel out of the loop once the entry has been correctly replaced. When the loop has been completed, it sends the new updated values to all clients subscribed to ‘leaderboard_scores’ by sending a pubnub.publish message. This is the complete Function script:
Build & Run
Now that you have your API keys and set up the Function in the Admin Portal, open scripts/leaderboard.cs in the project. Replace the publish and subscribe key with your keys.
The code below is the entire leaderboard.cs script. When the script runs for the first time, it initializes PubNub and sends a Fire message to the Function. This fire object tells the Function to send back the most recent data, which is stored in the database (KV Store). When the client gets a response from the Function, it runs the pubnub.SubscribeCallback and iterates through the dictionary, replacing any data that has changed since the last update.
Each player's UUID is set to a random number. However, when creating your game, you need to associate this value to a unique user ID so that players can’t have the same usernames in your real-time leaderboard.
The TaskOnClick function takes the information that is entered in the input fields as the parameters and publishes that data to the channel ‘submit_score’ that triggers the Function, which then updates all subscribers of the ‘leaderboard_scores’ channel.
When you run the project, a PubNub Fire message is sent to the Function that was created earlier. When there are no scores stored in the KV Store, it will instantiate every unfilled entry as “unset”. In the screenshot below, some entries have been added to the leaderboard KV Store by typing in a username and score.
Add another player score entry, Ted - 501, to the leaderboard. To do this, type ‘Ted’ in the username input field and ‘501’ in the score input field. Then click ‘Publish Score’.
Since Ted’s current score is lower than Jj’s score and higher than Billy’s score, it’s placed at spot 3, and Bob’s score is removed from the leaderboard. All players that are connected to the game will see this score update in real time. The sort order is all done in the Function implemented earlier using the KV Store and array sorting.
Now you have a working, real-time Unity leaderboard for your game!
What's Next after adding a score system in unity
Take advantage of PubNub services to easily build real-time interactions with enterprise-grade security, scalability, and reliability. PubNub eliminates the time it takes to set up and manage your infrastructure so you can focus on game development. Remember, you can view the video walkthrough of this tutorial on YouTube, as well as view the finished project in the GitHub repository.
Interested in doing more with your game and PubNub? Check out these resources:
Explore PubNub's Unity Developer Path, a guided journey in how you can use PubNub's Unity SDK to build real-time games with ease.
Play our Unity demo PubNub Prix, a racing game where you can chat with other players in and view leaderboard updates in real time.
Learn how to add PubNub to your Unity game in our How-to guide.
Learn how to develop your own scoring system and leaderboard for games in our gaming how-to guides.
Follow our step-by-step tutorial to set up and build the Unity game PubNub Prix.
Dive into our documentation for the PubNub Unity SDK, to learn how to customize PubNub's features that uniquely fit your application.
Have suggestions or questions about the content of this post? Reach out to devrel@pubnub.com.
