Revision as of 02:41, 12 June 2022

Scoreboard commands

ClearColumns - Deletes any and all previously defined columns. At least one column must be defined afterwards or else Zandronum will throw a fatal error!

Scoreboard <"title name">
{
    TitleFont = <font>
    SubtitleFont = <font>
    HeaderFont = <font>
    RowFont = <font>
    TitleColor = <text color>
    SubtitleColor = <text color>
    HeaderColor = <text color>
    RowColor = <text color>
    LocalRowColor = <text color>
    LocalRowDemoColor = <text color>
    BackgroundColor = <color>
    LightRowBackgroundColor = <color>
    DarkRowBackgroundColor = <color>
    BackgroundAmount = <value>
    RowBackgroundAmount = <value>
    BackgroundBorderSize = <value>
    GapBetweenTitleAndSubtitles = <value>
    GapBetweenHeaderAndRows = <value>
    GapBetweenSubtitles = <value>
    GapBetweenColumns = <value>
    GapBetweenRows = <value>
    HeaderHeight = <value>
    RowHeight = <value>
    Flags = <flag1> [, flag2 [, ...]]
    ColumnOrder = <column1> [, column2 [, ...]]
    RankOrder = <column1> [, column2 [, ...]]
    AddToRankOrder = <column>
}

The scoreboard's title is what gets printed at the top of the scoreboard (e.g. "RANKINGS").
TitleFont - The font used to draw the title. By default, this is BigFont.
SubtitleFont - The font used to draw all of the text that appears underneath the title, including the server hostname, current game mode, and game limits. By default, this is SmallFont.
HeaderFont - The font used to draw the column's header. By default, this is SmallFont.
RowFont - The font used to draw the rows for each player. By default, this is SmallFont.
TitleColor - The text colour to draw the title. By default, this is Red.
SubtitleColor - The text colour to draw the header's subtitles (server hostname, current game mode, and game limits). By default, this is Grey.
HeaderColor - The text colour used for the column's header. By default, this is Red.
RowColor - The text colour used for the rows of all players. By default, this is Grey.
LocalRowColor - The text colour used for the row of the player you're spying. By default, this is Green.
LocalRowDemoColor - Similar to the local row colour, but only when watching a demo. By default, this is Gold.
BackgroundColor - The colour of the background behind the entire scoreboard. By default, this is "00 00 00".
LightRowBackgroundColor - The "light" background colour of the row. By default, this is "40 40 40".
DarkRowBackgroundColor - The "dark" background colour of the row. By default, this is "20 20 20".
BackgroundAmount - The opacity of the scoreboard's background. A value of 1.0 represents fully opaque, while 0.0 represents fully transparent.
RowBackgroundAmount - The opacity of the row's background. This works similarly to BackgroundAmount.
BackgroundBorderSize - The spacing between the edges of the scoreboard's background and the text, in pixels.
GapBetweenTitleAndSubtitles - The spacing between the title and subtitles in the scoreboard's header, in pixels.
GapBetweenHeaderAndRows - The spacing between the column's header and the player rows, in pixels.
GapBetweenSubtitles - The spacing between the different lines of subtitles in the scoreboard's header, in pixels.
GapBetweenColumns - The spacing between the columns, in pixels.
GapBetweenRows - The spacing between the player rows, in pixels.
HeaderHeight - The height of the header. If entered as a negative number, then the height will be added onto the header font's height.
RowHeight - The height of each row. If entered as a negative number, then the height will be added onto the row font's height.
Flags - Can be one of the following:
- USETEAMTEXTCOLOR - Row text will be printed in the same colour as a player's team in team-based game modes.
- DONTSHOWHEADER - Prevents the scoreboard's header from being shown.
- DONTSHOWTEAMHEADERS - Prevents any of the team headers from being shown.
- DONTDRAWBORDERS - Don't draw any borders on the scoreboard.
- DONTFADEOUTDEADPLAYERS - Players that are dead don't appear faded out (i.e. less opacity, no row background).
- DONTSEPARATETEAMS - Players aren't divided into their respective teams and appear on a single list.
ColumnOrder = <column1> [, column2 [, ...]] - By default, columns are ordered from left to right on the scoreboard in the same order that they're defined in. This means that columns defined first will be on the left, while columns defined last will be on the right. If this command is used, the user can decide how exactly they would like to order the columns. Any defined columns missing from this list will be put on the right. Columns should be entered in by type for standard columns, or name for custom columns.
RankOrder = <column1> [, column2 [, ...]] - This decides how players will be sorted. Columns entered first have the highest priority over those entered last. If no rank order is specified, players can only be sorted by their number. Columns should be entered in by type for standard columns, or name for custom columns.
AddToRankOrder = <column> - Adds one single column to the end of the rank order list. Columns should be entered in by type for standard columns, or name for custom columns.

Note: a row's light and dark background colour doesn't have to be exactly "light" or "dark" in any sense. You're welcome to use any two colours, or make them both the same.

Column commands

Standard columns

Standard columns are built-in column types that Zandronum updates on its own. Users are allowed to customize the column to their own liking.

Column <type>
{
    DisplayName = <string>
    ShortName = <string>
    Alignment = <value>
    Width = <value>
    OverrideColumnGap = <value [, <left | right>]
    Flags = <flag1> [, flag2 [, ...]]
    GameMode = <gamemode1> [, gamemode2 [, ...]]
    GameType = <gametype1> [, gametype2 [, ...]]
    EarnType = <earntype1> [, earntype2 [, ...]]
    [Flags]
}

A column's type can be one of the following:
- Name - The player's current name. Every scoreboard must have this column or else Zandronum will throw a fatal error!
- Time - How long the player has been in the current game, in minutes.
- Frags - The player's frag count.
- Points - The player's point count.
- Wins - The player's win count.
- Kills - The player's monster kill count.
- Deaths - The player's death count.
- Assists - How many times this player earned the "assist" medal.
- Secrets - How many secrets this player discovered.
- Lives - How many lives this player still has. This column doesn't appear if players are supposed to have only one life.

DisplayName - Determines what will be used in the column's header. If this property isn't specified, then the display name will use the same text as its type instead.
ShortName - A shorter or abbreviated version of the column's display name, used if the scoreboard is too wide to fit on the user's screen and needs to be shrunken down as much as possible. If unspecified, the display name will always be used.
Alignment - Determines how the contents of the column are aligned, and can be one of the following: left, center, or right. By default, the column is aligned to the left.
Width - The maximum width of the column, in pixels. In case the scoreboard is too wide and needs to be shrunken down, this column could be narrower than what's specified.
OverrideColumnGap - This overrides the value of ColumnGap from the scoreboard block to control the amount of spacing from the column that comes from the left of this one.
Flags - Can be one of the following:
- REVERSEORDER - Sorts players in reverse (i.e. from least to greatest).
- INTERMISSIONONLY - This column only appears on the intermission screen.
- NOINTERMISSION - This column won't appear on the intermission screen.
- NOSPECTATORS - Don't draw the contents of this column for true spectators.
- OFFLINEONLY - This column only appears in offline games.
- ONLINEONLY - This column only appears in online games.
- HIDDENBYDEFAULT - Don't show this column at the start of the game.
- DONTSHOWHEADER - Prevents this column's header from being shown.
- DONTRESETONLEVELCHANGE - This column's values won't be reset to their default when the level changes. This only works on custom columns.
GameMode - A list of game modes where this column is active. By default, columns are active in all game modes. Refer to GAMEMODE for a list of all built-in game modes.
GameType - If specified, this column is active in any game modes that are of the following type: cooperative, deathmatch, or teamgame.
EarnType - If specified, this column is active in any game modes where players earn any of the following: kills, frags, points, or wins.
RequiresTeams - This column is only active in game modes that support teams (e.g. TDM, TLMS, CTF).
RequiresNoTeams - This column is disabled in game modes that support teams.
RequiresLives - This column is only active in game modes where players have lives (e.g. Survival, LMS, TLMS).
RequiresNoLives - This column is disabled in game modes that use lives.
RequiresTeamItem - This column is only active in game modes where a team's item is used (e.g. CTF or Skulltag).
RequiresNoTeamItem - This column is disabled in game modes that use team items.

Custom columns

Modders can define custom columns for their own needs. They will be responsible for updating the values of these columns on their own via ACS. Custom columns support all the commands as standard columns, plus a few extra commands.

CustomColumn <data type>, <name>
{
    DefaultValue = <value>

    // Bool column commands
    TrueText = <string>
    FalseText = <string>

    // Int, bool, float, and string column commands
    Length = <value>

    // Color and texture column commands
    ClipRectWidth = <value>
    ClipRectHeight = <value>
}

A column's data type can be one of the following:
- Int - Draws the column contents as an integer.
- Bool - Treats the column as a boolean and draws two different strings depending on the value:
  - TrueText - What's shown if the value is 1. By default, this is "true".
  - FalseText - What's shown if the value is 0. By default, this is "false".
- Float - Draws the column's contents as a float or fixed-point number.
- String - Draws the column's contents as text.
- Color - Draws the column with a single hexadecimal colour. A rectangular box is filled inside the column:
  - ClipRectWidth - The width of the box where the colour is drawn. If zero or unspecified, then it's the same as the column's width.
  - ClipRectHeight - The height of the box where the colour is drawn. If zero or unspecified, then it's the same as the row height.
- Texture: Draws the column with a graphic or texture. The name of the graphic must be entered as a string.
  - ClipRectWidth - The maximum width of the image that will be drawn, from the left-side of the image. If zero or unspecified, then there's no cut-off width.
  - ClipRectHeight - The maximum height of the image that will be drawn, from the top-side of the image. If zero or unspecified, then it's the same as the row height.
The column's name is what's used to reference the column. ACS functions use this name to find the column.
DefaultValue - The default value of this column at the start of a new game.
Length - This has different implications depending on the data type:
- Int - Limits the number of digits that are shown. This means that a number like 255 will appear as "99" if only two digits are allowed.
- Float - Limits the number of decimals that are shown. This means that a number like 3.14159 will appear as "3.14" if only two decimals are allowed.
- Bool and String - Limits the number of characters. Longer messages are truncated with an ellipsis at the end.

Example Images

The scoreboard in a deathmatch game.

The scoreboard in a CTF game. This game mode uses the team's flag item, so it's good to also show how many "Assists" the players have.

The scoreboard in a Team LMS game. Notice that dead spectators are drawn with less opacity and without the row's background colour to distinguish them from live players.