Leaderboard
Leaderboards can be used to display a player's score and ranking in game effects that keep track of score results.
Leaderboard data won't be correct while using the Scene or Preview panels. Accurate results will appear once your effect is published.
Add Leaderboard
To add a Leaderboard object:
- Go to the Hierarchy panel
- Click the Add object button [+]
- Go to Social
- Choose a leaderboard type
- Friends Leaderboard: shows your rank compared to your TikTok friends
- National Leaderboard: shows your rank against other players in your country
- Global Leaderboard: shows your rank against players around the world
Customize the Leaderboard Object
Ranking Mode
There are 3 available ranking modes to display for your leaderboard. These are:
- Friends: shows the player's rank among their list of friends
- National: shows the player's rank among other players in the country
- Global: shows the player's rank among other players around the world
When you select a category, the ranking values of the other two lists are displayed at the bottom of the leaderboard.
Score
The score cannot be modified in the Inspector panel. You will have to utilize Visual Scripting, using the pin to graph feature, instead. Data will be sorted and presented in the leaderboard. Learn more about Leaderboard in the Visual Scripting Panel.
Sort By
- High to Low: the player with the highest score will be listed first
- Low to High: the player with the lowest score will be listed first
Background Color
Customize the background color of the leaderboard that will be displayed. The available colors are Yellow, Purple, Pink, Orange, Green, and Gray.
Title Font
Change the style of the text displayed on the screen. The available fonts are TikTok Sans, Classic, Elegance, Vintage, Comic Sans, Serif, Freehand, and Luxury.
Leaderboard in the Visual Scripting Panel
In Visual Scripting, you can use a set of Leaderboard nodes to load creator data, show rankings in a custom UI, and post new scores as they play. Learn more about how Visual Scripting works.
Initialize Leaderboard node
To get started, add the Initialize Leaderboard node so your effect can request leaderboard information from the server right when the effect begins. Set the node's Sort By property to match your game's logic (High to Low or Low to High).
After the data is received, the node pulses and provides the creator's best score and ranks. Use these outputs to trigger feedback, such as celebrating a new personal best score.
Add the Initialize Leaderboard node
To add the Initialize Leaderboard node:
- Go to the Visual Scripting panel
- Right-click anywhere in the panel
- Click Add node
- Go to Social Info
- Select Initialize Leaderboard
Learn more about the available Input and Outputs of the Initialize Leaderboard node.
Get Leaderboard Info node
Next, add the Get Leaderboard Info node to populate your custom leaderboard UI. This node provides information about the best creators among Friends, National, or Global categories. The Index field accepts values 1 to 6. If the current creator is not in the top 6, the current creator's information is provided at index 6. Use the Info Available and Is Current User booleans to keep your leaderboard clean and to highlight the creator entry.
The node outputs a creator's best score and ranking and will reflect the latest values once the leaderboard is updated by the Update Leaderboard Score node.
Add the Get Leaderboard Info node
To add the Get Leaderboard Info node:
- Go to the Visual Scripting panel
- Right-click anywhere in the panel
- Click Add node
- Go to Social Info
- Select Get Leaderboard Info
Learn more about the available Input and Outputs of the Get Leaderboard Info node.
Update Leaderboard Score node
The final node in the flow is the Update Leaderboard Score node. When you execute the Update Score port, the value from the Score port is recorded and all leaderboard information is refreshed. This recalculation changes the results returned by the Get Leaderboard Info node, so it is a good idea to rebuild your custom leaderboard each time the score is updated.
Each update also recalculates the creator's current rank, so make sure to celebrate with the creator when they reach a new record.
At the end of the game, execute the Post Final Score port to write the creator's record to TikTok's servers when they publish a video. Only the creator's highest score is stored, ensuring the leaderboard always reflects their best result.
Add the Update Leaderboard Score node
To add the Update Leaderboard Score node:
- Go to the Visual Scripting panel
- Right-click anywhere in the panel
- Click Add node
- Go to Social Info
- Select Update Leaderboard Score
Learn more about the available Input and Outputs of the Update Leaderboard Score node.
Example Use Cases
We created three example projects to demonstrate different ways to use these nodes when building a custom leaderboard. You can download any of the example projects and import them into Effect House as templates, then customize them to fit your experience.
Demo Effect: Global Leaderboard UI Customization
Download the following project for this demo:
Demo Effect: Display First Place and Current Creator Ranking
Download the following project for this demo:
Demo Effect: Display Top Score and Current Creator Rank and Score
Download the following project for this demo:
