Spine Tutorial 3 - Scores - Clockwork Origins

Requirements

Ikarus script package: Thread @ World of Gothic
LeGo script package: Thread @ World of Gothic
Spine script package: Download @ GitHub
Tutorial 1 – Initialization

Introduction

This tutorial explains how to insert and manage highscores including rankings. Required is the module SPINE_MODULE_SCORES. Scores are useful for modifications like Elemental War, JiBo, Battle of the Kings, DoodleGoth, Sumpfkrautscavenger and the GothicRacer.

Scores

First we want to specify what exactly a score is. This can be easily displayed in a table.

Rank	Username	Score
1	Diego	1000
2	Gorn	900
2	Lester	900
4	Milten	800

Every player gets a rank relative to his scores. The sorting will be handled by Spine. As user of the score module you just need to set a score and then are able to query all values.

Additionally Spine provides the possibility to create multiple such rankings for a modification. These are identified via an ID. An ID can be related to game mode or a level. They are unique and begin with 0.

The default order for scores is descending which means the highest score is the best one. In the Management dialog you can change that to ascending when you want e.g. best times where usually the rule is the lower the better.

The Functions

The different functions of the score module shall be explained here.

Spine_UpdateScore

With Spine_UpdateScore the score of the current user can be changed for a given ID. To insert a value into the table from the example above the following code needs to be executed:

Spine_UpdateScore(0, 1001);

With this the player will reach rank 1.

Spine_GetUserScore

With Spine_GetUserScore the score for the current Spine user for a given ID can be queried again. That means with

Spine_GetUserScore(0);

you get the value 1001 when executed the previous example.

Spine_GetUserRank

With Spine_GetUserRank you can query the rank of the current Spine user and a given ID. That means

Spine_GetUserRank(0);

will return 1 after execution of the previous examples.

Spine_GetScoreForRank

Using Spine_GetScoreForRank the score for a given rank and an ID can be queried. With

Spine_GetScoreForRank(0, 1);

1001 will be returned. Querying rank 2 would return 1000.

Important Note: When two players have the same score they are sorted alphabetically and will be identified with their place in the table, not their rank. E.g. Gorn and Lester both have rank 3 in the example, but with Spine_GetScoreForRank(0, 3) you would receive the score for Gorn, with Spine_GetScoreForRank(0, 4) the one for Lester. That’s not that important for the score, but will be for the corresponding username.

Spine_GetUsernameForRank

With Spine_GetUsernameForRank the name for the player on the given rank and ID can be queried. That means

Spine_GetUsernameForRank(0, 1);

will return the name of the current player. For rank 2 you will get Diego.

Important Note: When two players have the same score they are sorted alphabetically and will be identified with their place in the table, not their rank. E.g. Gorn and Lester both have rank 3 in the example, but with Spine_GetUsernameForRank(0, 3) you would receive Gorn, with Spine_GetUsernameForRank(0, 4) the one for Lester.

Note

As shown in the examples the usage is very easy. But it’s important to know that scores are always overwritten. So if you want to only add higher scores than before you have to handle that yourself in your code. But that’s also very easy as shown in the following example:

var int newScore; newScore = 100;
if (newScore > Spine_GetUserScore(0)) {
	Spine_UpdateScore(0, newScore);
};

Getting Scores into the Spine database

Well, so far you can use the scores in the scripts, but your database entry in Spine won’t show that the game has scores and also not show the leaderboards.

To get this done, just do the following:

Start Spine
In the menu bar on top select “Developer” => “Management”
Select your modification on the left side
Switch to the “Scores” tab
Enter all your score details in here
After you entered everything, just submit

Now the scores will appear on your info page, the library and the profile and can be set from within the game.

Check out the tutorial Publishing on Spine.

Spine Tutorial 3 – Scores