Leaderboards

Learn how to use the Leaderboard Standard

The Leaderboard Standard leverages the World Protocol to store flexible and composable data that any game or dapp can read easily.

Connect with Us!

First of all, if you are a game developer looking to setup a Leaderboard or use BOOM DAO tooling for your game, please reach out to us in the BOOM DAO Discord. We would love to have a call with you to know the needs of your game and assist you in setting up your World canister for the first time. We will even do all the work to set it up for you, so all you have to worry about is writing your Unity code :)

How to Set-Up a Leaderboard?

To setup a Leaderboard in your game, first you must deploy a World canister from the Deploy Worlds tab on the Game Launcher website.

Once you have a World canister deployed, you can tap the "Configure World" button to open the Candid UI and start configuring your World.

To configure a Leaderboard, go to the createAction() function in the Candid UI and configure an Action that looks like this:

The above Action will increment the "score" column of the user in the Leaderboard by 1 whenever they call the Action. You can create any amount of columns in your Leaderboard with any name, simply add another updateEntity outcome and specify a different field name.

With this flexible data format, any type of data can be represented in a Leaderboard. And certain actionConstraints can be applied to prevent a user from scoring on the Leaderboard until they've met certain criteria.

For example, if you want the user to complete a race or win a battle before scoring a point on the Leaderboard, then simply check the actionConstraint checkbox and specify an entityConstraint that they must have a certain "wonBattle" or "finishedRace" Entity before being able to score points on the Leaderboard.

The reason the targetAction is filled out, but not the callerAction, is that Leaderboard entities are being written to the "UserNode" canister associated with the World canister ID itself, and not a user ID. We call this the WorldNode canister. When a client is calling this Action, the client will specify that the targetPrincipalId is the World canister ID. This way, all Leaderboard data is stored in the WorldNode canister associated with the World canister ID, and can be scalable to the needs of the game.

Configuring a Leaderboard action is as simple as specifying a targetAction with an outcome of incrementNumber or setText. And then specifying a gid (groupId) with the name of your Leaderboard. The eid (entityid) should be the user's principal id. To configure this, use the $caller keyword in the eid field and it will insert the caller's principal id at runtime.

The Entities in the Leaderboard group represent each user row of the Leaderboard. By leveraging Entities in the World Protocol, Leaderboard data follows a standard format that is universally readable. One game can even write to the Leaderboard of another game if it has permission to do so.