Category: Interface
Since engine version: 1.0 OC
SetScoreboardData
Description
Sets data in the scoreboard. The scoreboard is a global data table which can be used by scenarios to keep track of each player's score or other data. By default, the scoreboard can be displayed with the Tab key but display can also be controlled using DoScoreboardShow.
The scoreboard is automatically created when data is set and automatically removed when all data is cleared.
Data is set using a row and column index. If the row or column of a specified index does not yet exist, it is created as soon as data in this row or column is set. It does not matter which numeric indices you use as long as they are unique. So you could also use player numbers, player IDs (see GetPlayerID), or team IDs (see GetPlayerTeam) as row or column index. In order to prevent different object scripts from accidentally using the same row or column index you can use the ScoreboardCol function which will create a unique column index from a given value. In this case you should still take care that all object scripts accessing the scoreboard are using matching row indices. Rows and columnd are not sorted by row or column index. You can use the SortScoreboard function for user defined sorting.
The scoreboard is automatically created when data is set and automatically removed when all data is cleared.
Data is set using a row and column index. If the row or column of a specified index does not yet exist, it is created as soon as data in this row or column is set. It does not matter which numeric indices you use as long as they are unique. So you could also use player numbers, player IDs (see GetPlayerID), or team IDs (see GetPlayerTeam) as row or column index. In order to prevent different object scripts from accidentally using the same row or column index you can use the ScoreboardCol function which will create a unique column index from a given value. In this case you should still take care that all object scripts accessing the scoreboard are using matching row indices. Rows and columnd are not sorted by row or column index. You can use the SortScoreboard function for user defined sorting.
Syntax
bool SetScoreboardData(int row_id, int coloumn_id, string text, int data);
Parameters
- row_id:
- Value greater than to equal to 0 or SBRD_Caption. Index of the row in which you want to set data. The constant SBRD_Caption indicates the first column which is to be used as column header.
- coloumn_id:
- Value greater than to equal to 0 or SBRD_Caption. Index of the column in which you want to set data. The constant SBRD_Caption indicates the first row which is to be used as row header.
- text:
- [opt] Text data to be set. If unspecified or 0, the cell is cleared. If a row is completely empty except for the header (SBRD_Caption), the row is removed. The same applies to columns. Row or column removal is only performed after clearing of a cell.
To display symbols or text in different colors you can use markup. - data:
- [opt] Extra data for these cells. This data is used to sort the scoreboard using SortScoreboard.
Remark
The cell in the top left corner is never displayed. Instead, the value for row_id == SBRD_Caption and coloumn_id == SBRD_Caption is displayed in the header. If no value is specified here, the scoreboard will not have a header and can not be moved using the mouse.
Example
protected func InitializePlayer(int player)
{
var player_id = GetPlayerID(player), coloumn_id = 1;
SetScoreboardData(SBRD_Caption, coloumn_id, "{{RVLR}}", coloumn_id);
SetScoreboardData(player_id, coloumn_id, "0" , 0);
SetScoreboardData(SBRD_Caption, SBRD_Caption, "Score", SBRD_Caption);
SetScoreboardData(player_id, SBRD_Caption, GetTaggedPlayerName(player), player_id);
SortScoreboard(coloumn_id, true);
Global(player)=0;
return true;
}
This might be a typical function for intializing the scoreboard in a scenario script: for each player a row is created. The row header is the player name and another column per row contains the starting score of 0.
To index the rows we are using the player id (iPlrID). This player id is unique for each joined player so newly joining or rejoining players will get a unique id as well. 1 is used as column index for the score.
The first call to SetScoreboardData sets the header of the score column to "{{RVLR}}"; which will display the picture of the rule object "Rivalry". The second call enters a "0" into the score column for the joining player. The third call sets the scoreboard title to "Score". The fourth call sets the row header (meaning the left column) to the player name and player color of the joining player.
By using SortScoreboard the scoreboard is then sorted in descending order. The global variable of player index is then set to 0 so we can keep track of the player's score here.
To index the rows we are using the player id (iPlrID). This player id is unique for each joined player so newly joining or rejoining players will get a unique id as well. 1 is used as column index for the score.
The first call to SetScoreboardData sets the header of the score column to "{{RVLR}}"; which will display the picture of the rule object "Rivalry". The second call enters a "0" into the score column for the joining player. The third call sets the scoreboard title to "Score". The fourth call sets the row header (meaning the left column) to the player name and player color of the joining player.
By using SortScoreboard the scoreboard is then sorted in descending order. The global variable of player index is then set to 0 so we can keep track of the player's score here.
protected func RemovePlayer(int player)
{
var player_id = GetPlayerID(player), coloumn_id = 1;
SetScoreboardData(player_id, coloumn_id, 0 ,0);
}
Another function in the same scenario script would remove the cell in the score column of a deleted player. If no other scripts have accessed the scoreboard, this would effectively completely remove the player from the scoreboard, since no other cells except headers would contain any data.
public func AddScore(int player)
{
var player_id = GetPlayerID(player), coloumn_id = 1, iScore = ++Global(player);
SetScoreboardData(player_id, coloumn_id, Format("%d", iScore), iScore);
SortScoreboard(coloumn_id, true);
DoScoreboardShow(1, player+1);
Schedule(Format("DoScoreboardShow(-1, %d)", player+1), 200);
}"
Finally, this function will add a score point for a player. The score is also set as extra data so the list can automatically be sorted by score.
Using DoScoreboardShow the scoreboard is displayed for the player receiving the point. The following call to Schedule will then hide the scoreboard after a few seconds (200 frames).
Using DoScoreboardShow the scoreboard is displayed for the player receiving the point. The following call to Schedule will then hide the scoreboard after a few seconds (200 frames).