Introduction

Each game created with WiMi5 has a ranking assigned to it by default. Using it is optional, and the decision to use it is totally up to the developer. It’s very easy to handle, and we can sum it up in three steps, which are explained below.

1. Firstly, the setup is performed in the Ranking section of the project’s properties, which can be accessed from the dashboard.
2. Then, when you’ve created the game in the editor, you’ll have a series of blackboxes available to handle the rankings.
3. Finally, once it’s running, a button will appear in the game’s toolbar (if the developer has set it up that way) with which the player can access the scoreboard at any time.

It is important to know that a player can only appear on a game’s scoreboard if they are registered.

Setting up the Rankings

Note:  Remember that since it’s still in beta, the settings are limited. So we need you to keep a few things in mind:

- The game is only assigned one table, which is based both on the score obtained in the game and on the date that score was obtained. In the future, the developer will be able to create and personalize their own tables.

- The ranking has several setup options available, but most of them are preset and can’t be modified. In later versions, they will be.

In the dashboard, in the project’s properties, you can access the rankings’ setup by clicking on the Rankings tab. As you can observe, there is a default setting.

For configuring the ranking, you will have the following options:

Display the button in the game’s toolbar

This option is selected by default, and allows the button to show rankings to appear on the toolbar that’s seen in every game. If you’re not going to use rankings in your game, or don’t want that button to appear, in order to have more control over when the scoreboard will be shown, all you have to do is deactivate this option. The button looks like this:

Only one result per user

NOTE: The modification of this option is turned off for the time being.

This allows you to set up whether a player can have multiple results on the scoreboard or only their best one. This option is turned off by default, meaning all the player’s matches with top scores will appear.

It’s important to note that if this option is turned off, the player’s best score is the only one that will appear highlighted, not the last. If the player has a lower score in a future match, it will be included in the ranking, but it may not be shown since there’s a better score already on the board.

Timeframe Selection

NOTE: The modification of this option is turned off for the moment, and is only available in all-time view, which is further limited to the 500 best scores.

This allows the scoreboard to have different timeframes for the same lists: all-time, daily, monthly, and yearly. The all-time view is chosen by default, which, as its name implies, has no time limit.

Match data used in rankings

NOTE: The modification of this option is turned off for the moment. The internationalization of public texts is not enabled.

This allows you to define what data will be the sorting criteria for the scoreboard. The Points item is used by default; another criterion available is Date (automatically handled by the system), which includes the date and time the game’s score is entered.

Of each of the data that is configured, we have the following characteristics reflected in the board columns:

• Priority: This indicates the datum’s importance in the sorting of the scoreboard. The lower the number, the more important the datum is. In the default case, for example, the first criterion is points; if there are equal points, then by date.
• ID: Unique name by which the datum is identified. This identifier is what will appear in the blackboxes that allow the rankings’ data to be managed.
• Type: The type of data.
• List order: Ascending or descending order. In the default case, it will be descending for points (highest number first), and should points be equal, by ascending order by date (oldest games first).
• Visible: This indicates if it should be shown in the scoreboard. That is to say, the datum is taken into account to calculate the ranking position, but it is not shown later on the scoreboard. In the default case, the points are visible, but the date and time are not.
• Header title: The public name of the datum. This is the name the player will see on the scoreboard.

It is possible to add additional data with the “+” button, to modify the characteristics of the existing data, as well as to modify the priority order.

Once the rankings configuration is reviewed, the next step is to use them in the development of the game.

Making use of the rankings in the editor

When you’re creating your game in the editor, you’ll find in the Blackboxes tab in the LogicChart that there’s a group of blackboxes called Rankings, in which you will find all the blackboxes related to the management of rankings. From this link you can access these blackboxes’ technical documentation. Nevertheless, we’re going to go over them briefly and see a simple example of their use.

SubmitScore Blackbox

This allows the scores of the finished matches to be sent.



This blackbox will be different depending on the data you’ve configured on the dashboard. In the default case, points is the input parameter.

When the blackbox’s submit activator is activated, the value of that parameter will be sent as a new score for the user identified in the match.

If the done output signal is activated, this will indicate that the operation was successful, whereas if the error signal is activated, that will indicate that there was an error and the score could not be stored.

If the accessDenied signal is activated, this will mean that a non-registered user tried to send a score, which will allow you to treat this matter in a special way (like showing an error message, etc.).

Finally, there is the onPrevious signal. If you select the blackbox and go to its properties, you’ll see there is one called secure that can be activated or deactivated. If you activate it, this blackbox will not send the game’s result as long as the answer to a previously-sent result is still pending. Therefore, onPrevious will activate if you try to send a game result when the answer to a previously-sent result is still pending, and the blackbox’s secure mode is activated.

ShowRanking Blackbox

This allows the scoreboard to be displayed (for example, at the end of a match). It has the same result as when a player presses the “see rankings” button on the game’s toolbar.



When this show input is activated, the scoreboard will be displayed. If it was displayed successfully, the shown output signal will be activated, and when the player closes the board, that will activate the closed output signal, which will allow us to also personalize the flow of how it’s run.

Example of the use of the blackboxes

If you want, for example, to send a player’s final score at the end of a match so that it appears on the scoreboard, you can do that this way:

Suppose you have a Script you manage the end of the game with and it shares a parameter with the points the player has accumulated up to that moment:

You’d have to create a SubmitScore blackbox...

…and join the gameEnded output (which, let’s say, is activated when the game has ended) to the submit input in the blackbox you just created. It will also be necessary to indicate the variable the score has that we want to send, points from the DetectGameEnd script in our case. So, click and drag it to the SubmitScore blackbox to assign it. With these two actions, you’ll get the following:

And the game would then be read to send scores. The player could check the board at any time by clicking on the menu button that was created for just that purpose, as we saw the setup section.

However, you could want the scoreboard to appear automatically once the match is over. To do that, use the ShowRankings blackbox which, for example, could join to the done output in the SubmitScore blackbox and thus show the scores as soon as the score has been sent and confirmed:

And with that you have a game that can send scores and show the scoreboard.

Running the game

Once a game that is able to send match results is developed, you have to remember that it behaves differently in “editing” than in “testing” and “production” mode.

By “editing” mode, we mean when the game is run directly in the editor, in the Preview frame, to perform quick tests. In this mode, the scores are stored, but only temporarily. When we stop running it, those scores are deleted. Also, in this mode, the scoreboard is “simulated”; it’s not real. This means that there’s no way to access the toolbar button, since it doesn’t really exist.

Sending and storing “real” scores is done by testing the games or playing their published versions. To test them, first you have to deploy them with the Deploy option on the Tools roll-down menu, and then with the Test option (from the menu or from the dialogue box you see after the Deploy one) you can start testing your game. In this mode, the scoreboard is real, not simulated, so the match scores are added to the ranking definitively.

Conclusion

Dealing with rankings in WiMi5 is very easy. Just configure the rankings you want to use. Then use the rankings blackboxes and let your players challenge between them trying to get the best score. If you don´t want to use a ranking in your game, just click on the settings to hide this feature.