SCORINFO

From Zandronum Wiki
Revision as of 15:18, 22 June 2023 by AKMDM (talk | contribs) (List what data types are supported too.)
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

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:
  1. Any data columns nested inside composite columns cannot be included in this list. Instead, the composite column should be added to the column order.
  2. 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

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.

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.
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.
ScoreIcon Texture The icon indicated by the Player.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:

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:
  1. The data columns cannot already be inside another composite column.
  2. The data columns cannot be included in the scoreboard's column order.
  3. The data columns must always have the DONTSHOWHEADER flag enabled, and be aligned to the left.
  4. 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.
Retrieved from ‘https://wiki.zandronum.com/w/index.php?title=SCORINFO&oldid=1800’