SCORINFO

This article documents a Zandronum-specific special lump which may not be supported by ZDoom and its other child ports.

This article documents a special lump which is only available in development builds of Zandronum 3.2 and newer.

(development version 3.2-alpha and above only) SCORINFO is a special lump that allows customization of the built-in scoreboard in Zandronum. This offers ways to change things like which fonts or colours are used, the sizing of elements (headers, columns, rows, gaps, etc.) on the scoreboard, what columns are to be displayed and how players are ordered by them, and more. Modders aren't the only people who can benefit from this lump. Regular players can also write their own SCORINFO lump and save into their skins folder, if they wish to design their own personal scoreboard.

Scoreboard block

The scoreboard block is used to change things that affect the entire scoreboard including its properties, what columns should appear and/or used to rank players, and starting margin sub-blocks. The block is set up like this:

Scoreboard
{
    MarginBlock
    {
        ...
    }

    Property = <value>
    AddFlag FLAGNAME1
    RemoveFlag FLAGNAME2
}

Properties

Property	Description
HeaderFont = "<font>"	The font used to draw the column's header.
RowFont = "<font>"	The font used to draw the rows for each player.
HeaderColor = "<text color>"	The text colour used on the column headers.
RowColor = "<text color>"	The text colour used on the rows of all players.
LocalRowColor = "<text color>"	The text colour used on the row of the player being spied on.
LocalRowDemoColor = "<text color>"	Similar to the LocalRowColor, except only used while watching a demo.
DeadPlayerTextAlpha = <value>	The opacity of the row's text for dead players.
BorderTexture = "<texture>"	The texture to use to draw the borders, if the USETEXTUREFORBORDERS flag is enabled. The texture is tiled from left to right along the width of the scoreboard, so ideally, the texture should be seamless.
LightBorderColor = "<color>"	The "light" border line colour, if the USEHEADERCOLORFORBORDERS flag is disabled.
DarkBorderColor = "<color>"	The "dark" border line colour, if the USEHEADERCOLORFORBORDERS flag is disabled.
BackgroundColor = "<color>"	The colour of the background drawn behind the entire scoreboard.
LightRowBackgroundColor = "<color>"	The "light" colour of the row background.
DarkRowBackgroundColor = "<color>"	The "dark" colour of the row background.
LocalRowBackgroundColor = "<color>"	The colour of the background of the row corresponding to the player being spied on.
BackgroundAmount = <value>	The opacity of the scoreboard's background.
RowBackgroundAmount = <value>	The opacity of the row's background.
DeadPlayerRowBackgroundAmount = <value>	The opacity of the row's background for dead players.
BackgroundBorderSize = <value>	The extra background space surrounding the contents of the scoreboard, in pixels.
GapBetweenHeaderAndRows = <value>	The spacing between the column headers and the player rows, in pixels.
GapBetweenColumns = <value>	The spacing between the columns, in pixels.
GapBetweenRows = <value>	The spacing between each of the player rows, in pixels.
ColumnPadding = <value>	How much extra padding to leave on both sides of a column, in pixels. This doesn't count as being part of the gap between two columns.
HeaderHeight = <value>	The height of the header. If entered as a negative number, then this value is added onto the header font's height.
RowHeight = <value>	The height of each rows. If entered as a negative number, then this value is added onto the row font's height.
ColumnOrder = "<column>" [, ...]	Controls the order in which columns appear on the scoreboard, from left to right. Both data columns and composite columns may be included in this list. A few things to note: Any data columns nested inside composite columns cannot be included in this list. Instead, the composite column should be added to the column order. If the list is redefined and some columns are removed from the list, then they're also removed from the rank order.
AddToColumnOrder = "<column>" [, ...]	Appends the column order list with the listed columns. The new columns will be added on the right side of the scoreboard.
RemoveFromColumnOrder = "<column>" [, ...]	Removes the listed columns from the scoreboard. If any data columns are removed from the column order, then they're also removed from the rank order.
RankOrder = "<column>" [, ...]	Controls the order in which players are ranked on the scoreboard, from top to bottom (e.g. frags, points, wins, kills, etc.). Columns at the beginning of the list have the highest priority, while columns at the end of the list have the least priority. Players with higher values (e.g. a higher frag count) will appear above those with lower values, unless the column enabled the REVERSEORDER flag, which inverts this behaviour. Only data columns (i.e. no composite columns) can be added to the rank order, and they must already be included in the column order.
AddToRankOrder = "<column>" [, ...]	Adds more columns to the rank order list. These columns will have less priority versus those that were already in the list.
RemoveFromRankOrder = "<column>" [, ...]	Removes the listed columns from the rank order list.

Note: The "light" and "dark" colours used on the borders and row backgrounds are just naming conventions and don't necessarily have to be "light" or "dark" in any sense. You're welcome to use any two colours, or make them both the same.

Flags

• USETEAMTEXTCOLOR

The row text will be printed in the same colour as the player's team in team-based game modes.

• USEHEADERCOLORFORBORDERS

The text colour of the headers is automatically used to colour the border lines that surround the column headers.

• USETEXTUREFORBORDERS

Instead of drawing the borders as a series of lines whose colours are controlled by LightBorderColor and DarkBorderColor, the texture specified in BorderTexture is used to draw the borders instead.

• SHOWGAPSINROWBACKGROUND

Reveals the gaps between columns in the row's background.

• DONTDRAWBORDERS

Prevents any borders from being drawn.

• DONTSEPARATETEAMS

Players aren't separated into their respective teams and appear on a single list. This also implies that team headers aren't drawn, though the spectator header is still visible.

• DONTUSELOCALROWBACKGROUNDCOLOR

Prevents LocalRowBackgroundColor from being used to draw the background of the row that corresponds to the player being spied on.

• DONTSHOWTEAMHEADERS

Prevents the team headers and the spectator header from being shown.

Margin blocks

Margins are sub-blocks that go inside a scoreboard block and are used to modify special sections on the scoreboard. There are four types of margins:

• MainHeader: appears above the column headers and player rows.
• TeamHeader: appear above all players row of a single team.
• SpectatorHeader: appears above all true spectator player rows.
• Footer: appears underneath all player rows.

Margin commands

Command	Description
MultiLineBlock	Starts a block of lines that consist of strings, colors, or textures.
RowBlock	Starts a row that consists of strings, colors, or textures.
DrawString	Draws text somewhere in the margin.
DrawColor	Draws a color box somewhere in the margin.
DrawTexture	Draws a graphic or image somewhere in the margin.
IfOnlineGame( <true/false> )	Executes a block if the current game is (not) a network game.
IfIntermission( <true/false> )	Executes a block if the intermission screen is (not) being shown.
IfPlayersOnTeams( <true/false> )	Executes a block if players are (not) supposed to be on teams.
IfPlayersHaveLives( <true/false> )	Executes a block if players are (not) supposed to have lives.
IfShouldShowRank( <true/false> )	Executes a block if the current player's rank should (not) be shown.
IfGameMode( <gamemode> [, ...] )	Executes a block when any of the given game modes are being played.
IfGameType( <gametype> [, ...] )	Executes a block when any of the given game types are being played. Possible values are cooperative, deathmatch, and teamgame.
IfEarnType( <earntype> [, ...] )	Executes a block when players can earn any of the given types. Possible values are frags, points, wins, and kills.
IfCVar	Executes a block depending on a CVar's value.
Else	Executes the following block if the condition of the previous "if" margin command (e.g. IfOnlineGame) fails.

Column block

The columns are where all the information on the scoreboard get organized in. There are two types of columns: data and composite. Both column types require a columnname which is the internal name they will use.

Data columns

Data columns are what hold the actual data contents. There are six possible data types: int, bool, float, string, color, and texture. To define a data column, set up the block like this:

Column "<columnname>"
{
    Property = <value>
    AddFlag FLAGNAME1
    RemoveFlag FLAGNAME2
}

Zandronum supports many built-in native column types which already have their own data and are updated automatically. A list of all native column types can be found below.

If the specified columnname doesn't match that of any native type, then the data column is a custom column.

Native types

Type	Data type	Description
Name	String	The name this player is using.
Index	Int	The player's index number.
Time	Int	How long this player has been playing in the current game.
Ping	Int	The player's ping measured in milliseconds.
Frags	Int	The player's current frag count.
Points	Int	The player's current point count.
Wins	Int	The player's current win count.
Kills	Int	The player's current kill count.
Deaths	Int	How many times this player has died.
Secrets	Int	The number of secrets this player has discovered.
Lives	Int	The number of lives this player still has.
Damage	Int	How much damage this player has dealt in a cooperative game, if sv_awarddamageinsteadkills is enabled.
Handicap	Int	The player's handicap value.
JoinQueue	Int	The player's position in the join queue.
Vote	String	What decision this player made for the current vote.
PlayerColor	Color	Shows what colour the player is currently using.
StatusIcon	Texture	Shows a mini icon that represents the player's current status (e.g. chatting, in the console or menu, or lagging).
ReadyToGoOn	Texture	Shows a mini icon to indicate whether or not the player is ready to go during the intermission.
PlayerIcon	Texture	The icon indicated by the ScoreIcon property of the player's current class.
ArtifactIcon	Texture	Shows an icon if this player is carrying a gamemode-specific item (e.g. terminator sphere, hellstone, the white flag, or another team's flag/skull).
BotSkillIcon	Texture	A mini icon that indicates the skill level of a bot.
CountryName	String	The full name of the country that the player is connecting from.
CountryCode	String	The country code that the player is connecting from.
CountryFlag	Texture	A mini icon of the flag of the country that the player is connecting from. The icons are organized in a 16x16 grid, inside a single texture called "CTRYFLAG".

How to use custom columns

Unlike native columns which already have data, custom columns don't come with data out of the box. So to create a custom column, you must also define the custom data that it will use inside the GameInfo block of a MAPINFO lump, using the AddCustomData property. The name of the custom data must match the name of the custom column.

Let's assume, for all intents and purposes, that we created a custom column named "MyCustomColumn" that uses integers with a default value of 0. The custom data would need to be defined like this:

GameInfo
{
    AddCustomData = "MyCustomColumn", "int", 0
}

Each player has their own value in a custom data set. The value(s) are automatically reset back to default for a single player when they disconnect from the server, or for all players at the start of a new game.

The custom data can be manipulated using several built-in ACS functions:

• GetCustomPlayerValue
• ResetCustomDataToDefault
• SetCustomPlayerValue

Composite columns

Composite columns consist of several or more data columns that are tucked underneath a single header - the composite column's. The values of the sub-columns are drawn from left to right. To define a composite column, set up the block like this:

CompositeColumn "<columnname>"
{
    Columns = "<column>" [, ...]
    Property = <value>
    AddFlag FLAGNAME1
    RemoveFlag FLAGNAME2
}

Note: The name of a composite column can't be the same as a native or custom data column. If this happens, Zandronum will throw a fatal error.

Properties

Property	Used for	Description
DisplayName = "<name>"	Any	The name that is used in the column's header.
ShortName = "<name>"	Any	A shorter or abbreviated version of the display name that's used when cl_useshortcolumnnames is enabled.
Alignment = <alignment>	Any	How the contents inside the column are aligned. Possible values are left, center, or right.
Size = <value>	Any	The size of the column, in pixels. This is the column's whole width, or padding if the ALWAYSUSESHORTESTWIDTH flag is enabled. If the column's header or contents can't fit inside its size, then the width will be increased to something large enough to fit everything.
GameMode = <gamemode> [, ...]	Any	A list of game modes where this column is only active in. If unspecified, then the column in active in all game modes.
GameType = <gametype> [, ...]	Any	The game types which this column is only active in. Possible values are cooperative, deathmatch, and teamgame. In unspecified, then the column is active in all game types.
EarnType = <earntype> [, ...]	Any	What kind of score the players must earn for this column to be active. Possible values are frags, points, wins, and kills. By default, columns are active for all earn types.
CVar = "<cvarname>"	Any	If a CVar is specified, then its value will decide if this column is active (if non-zero) or disabled. Enabling the CVARMUSTBEZERO flag reverses this behaviour. The CVar must be either an integer, boolean, or a flag.
MaxLength = <value>	Bool, Float, String	Limits how many decimals (for the float data type), or characters (for bool and string data types) are shown.
Prefix = "<text>"	Int, Bool, Float, String	The text that will be added to the beginning of a value.
Suffix = "<text>"	Int, Bool, Float, String	The text that will be added to the end of a value.
ClipRectWidth = <value>	Color, Texture	The width of the clipping rectangle. Any pixels outside of the clipping rectangle aren't drawn.
ClipRectHeight = <value>	Color, Texture	The height of the clipping rectangle.
TrueText = "<text>"	Bool	The text that is drawn when a player's value is 1 (or true).
FalseText = "<text>"	Bool	The text that is drawn when a player's value is 0 (or false).
GapBetweenColumns = <value>	Composite	The spacing between each of the data columns that are inside a composite column, in pixels.
Columns = <column> [, ...]	Composite	Specifies which data columns belong to the composite column, and their order from left to right. A few things to note: The data columns cannot already be inside another composite column. The data columns cannot be included in the scoreboard's column order. The data columns must always have the DONTSHOWHEADER flag enabled, and be aligned to the left. If the list is redefined and some columns are removed from the list, then they're also removed from the scoreboard's rank order.
AddToColumns = <column> [, ...]	Composite	Appends the composite column's list with the listed columns. The new columns will be added on the right.
RemoveFromColumns = <column> [, ...]	Composite	Removes the listed columns from the composite column's list. If any data columns are removed from the list, then they're also removed from the scoreboard's rank order.

Flags

• REVERSEORDER

By default, players are sorted from highest to lowest value in a column. By enabling this flag, players will be sorted from lowest to highest value instead.

• INTERMISSIONONLY

The column is only active on the intermission screen.

• NOINTERMISSION

The column is disabled on the intermission screen.

• NOSPECTATORS

The contents of this column are never drawn for true spectators.

• OFFLINEONLY

The column is only active in offline (i.e. singleplayer or with bots) games, and never used in online games.

• ONLINEONLY

The column is only active in online games, and never used in offline games.

• REQUIRESTEAMS

This column is only active in game modes that support teams.

• FORBIDTEAMS

Disables the column in game modes that support teams.

• REQUIRESLIVES

This column is only active in game modes where players have lives.

• FORBIDLIVES

Disables the column in game modes that use lives.

• REQUIRESTEAMITEMS

This column is only active in game modes where a team's item is used.

• FORBIDTEAMITEMS

Disables the column in game modes that use team items.

• DONTSHOWHEADER

Prevents the column's header from being shown.

• ALWAYSUSESHORTESTWIDTH

The width of the column is set to whatever's small enough to still fit everything (i.e. the header and contents) inside of it. The column's size will be treated as a padding and increase its width by the specified amount.

• CVARMUSTBEZERO

The CVar used by this column uses must be equal to zero (or false) for it to still be active.

• DISABLEIFEMPTY

Disables the column whenever it has no contents inside of it.