Minecraft:Scoreboard

A screenshot of a scoreboard on the right side of the screen.

The scoreboard system is a complex gameplay mechanic utilized through Minecraft:commands. Mainly intended for mapmakers and server Minecraft:operators, scoreboards are used to track, set, and list the scores of Minecraft:entities in a myriad of different ways.

Objectives

An objective tracks a score for entities while meeting a single criterion. These scores are stored as 32-bit integer ranging from -2³¹ to 2³¹-1.Template:Fn

Objectives have two main properties: a name and a criterion. The objectives' name is used internally for referencing in commands, target arguments, and the file format, while the criterion determines the objectives' behavior – primarily what to track.

Template:IN, the objectives' name must be a single, case-sensitive string consisting of Template:W characters (A–Z and 0–9), hyphen Template:Cd, plus Template:Cd, dot Template:Cd, and underscore Template:Cd. Template:IN, it must either be a single string that has no space or a quoted string. When a string is quoted, backslash Template:Cd can be used to escape characters.

The entity's score in any objective can be changed from commands, unless it's read-only and automatically set by the game (see Template:Slink). It can be increased by, decreased by, or set to a given amount with commands. Non-player entities only support dummy criterion in the scoreboard; their scores can only be changed by commands and not automatically by the game. Unlike players, when a non-player entity dies, its scores are deleted. Notable commands that can modify any entities' scores are Template:Cmd and Template:Cmd (the latter is exclusive to Java Edition only).

The score holder's name can either be the player's Minecraft:username or the entity's Minecraft:UUID. For players, the score holder's name doesn't need to belong to an actual Minecraft:player, and can be specified by any arbitrary username.

Objectives also have other properties to change its appearance and behavior: {{#VARDEFINE:boolean_true|Boolean: true (default) or false}}

Property	Description	Value
displayname	The objective's display name that appears on display slots, such as the player list, below the player's name tag, and the sidebar. By default, the objective's name is the display name.	Minecraft:Text component
numberformat	The objective's number format for the score. The value can be `blank`, `fixed`, or `styled`.	`blank` displays nothing on the scoreboard. `fixed` displays the contents specified in the command. `styled` displays the score number with the styling applied from the Minecraft:text component format, such as Template:Nbt, Template:Nbt, Template:Nbt, etc. This means that the Template:Nbt property is ignored.
rendertype	How the score is rendered in the player list (all other display locations are unaffected). The value can be `integer` (the default) or `hearts`.	`integer` the score is rendered as an integer. `hearts` the score is rendered in the form of hearts (half a heart for each point). Values below 1 are not rendered. Values above 43 are instead rendered as `<full-hearts>hp`, where `<full-hearts>` is the floating-point representation of `value / 2`.
displayautoupdate	Whether or not to display auto updates when the score has changed.	{{#VAR:boolean_true}}

The number format property and the score holder's name can be changed per-entity using Template:Cmd.

Server Minecraft:operators can select entities by their scores using Minecraft:target selector with the "scores" argument (syntax: @e[scores={<name>=<min>..<max>}]). This argument uses the <name> argument to specify the score name of the objective. For example, inputting Template:Cmd into a Minecraft:command block triggers a Minecraft:comparator or conditional command block if any player has died at least once ever since the objective was created, assuming the deaths objective has the deathCount criterion.

Template:Fnlist

Criteria

A criterion determines an objective's behavior and tracks statistical game elements. When a criterion's source value changes, the change is automatically reflected in the objective's score.

Template:IN, criteria are categorized by single and compound criteria. Each of the criteria tracks specific game elements, such as players' Minecraft:health, Minecraft:hunger, Minecraft:experience, Minecraft:triggers, Minecraft:statistics, and among other things. Template:IN, the "dummy" criterion is the only criteria supported. As such, scores can only be changed by commands.

Single criteria

Template:Exclusive

Single criteria names consist of an alphabetical string.

Criteria name	Description	Can be modified
dummy	A score that can be changed only by commands and not automatically by the game. This can be used for storing integer states and variables, which can then be used with the scoreboard's operations to perform arithmetic calculations.	Template:Tc
trigger	A score that can be changed by commands and not automatically by the game. The Template:Cmd command allows players to set, increment, or decrement their own score. The command fails if the objective has not been "enabled" for the player using it. After a player uses it, the objective is automatically disabled for them. By default, all trigger objectives are disabled for players. Ordinary players can use the Template:Cmd command, even if Minecraft:cheats are disabled or they are not server operators, making it useful for safely taking input from non-operator players.	Template:Tc
deathCount	The score increments automatically when a player dies.	Template:Tc
playerKillCount	The score increments automatically when a player kills another player.	Template:Tc
totalKillCount	The score increments automatically when a player kills another player or a mob.	Template:Tc
health	Ranges from 0 to 20 (and greater) for a normal player; represents the amount of half-hearts a player has. It may appear as 0 for players before their health has changed for the first time. The health score can surpass 20 points with extra hearts from Minecraft:attributes, Minecraft:Health Boost or Minecraft:Absorption effects.	Template:Tc
xp	Matches the total amount of Minecraft:experience the player has collected since their last death.	Template:Tc
level	Matches the current experience level of the player.	Template:Tc
food	Ranges from 0 to 20; represents the amount of hunger points a player has. It may appear as 0 for players before their food level has changed for the first time.	Template:Tc
air	Ranges from 0 to 300; represents the amount of air a player has left while Minecraft:swimming underwater. It matches the air NBT tag of the player.	Template:Tc
armor	Ranges from 0 to 20; represents the amount of armor points a player has. It may appear as 0 for players before their armor level has changed for the first time.	Template:Tc

Compound criteria

Template:Exclusive

Compound criteria names are divided into parts, delimited with periods Template:Cd. For example, Template:Cd is a valid compound criterion, under which a player's score increments whenever they are killed by a zombie.

Objectives based on a compound criterion are writable and can be modified with commands.

Minecraft:Statistics can be used as compound criteria whose name are their identifier. Player statistics are stored separately from the scoreboard, and as they update, the scores in these objectives are updated too.

In addition, there are some other compound criteria: {{#VARDEFINE:team_colors|Template:Cd }}

Criteria base name	Description	Number of sub-criteria
teamkill.<team_color>	Sub-criteria include team colors. Player scores increment when a player kills a member of the given colored team. These criteria follow the complete format `teamkill.<team_color>`, where `<team_color>` is a color from the list: Template:Collapse	16
killedByTeam.<team_color>	Sub-criteria include team colors. Player scores increment when a player is killed by a member of the given colored team. These criteria follow the complete format `killedByTeam.<team_color>`, where `<team_color>` is a color from the list: Template:Collapse	16

Score operations

Players can increment, decrement, reset and modify an entity's scores by a specific amount using Minecraft:commands. They can also set scores to a Minecraft:random number within a range, and test if the scores are set between specific minimum and maximum values.

Scores can also be modified by using arithmetic operations like addition, subtraction, multiplication, and etc. These operations take the target entity's score and execute it with another score from a different entity. The result of such operations is then assigned as the new target score.

For example, executing an addition operation on a target entity's score with a source entity's score can be expressed as:

<math>\text{New Target Score} = \text{Target Score} + \text{Source Score}</math>

Below is a list of available arithmetic operations.

Operation	Description
+=	Adds the target's score and the source's score. <math>\text{New Target Score} = \text{Target Score} + \text{Source Score}</math>
-=	Subtracts the target's score and the source's score. <math>\text{New Target Score} = \text{Target Score} - \text{Source Score}</math>
*=	Multiplies the target's score and the source's score. <math>\text{New Target Score} = \text{Target Score} \times \text{Source Score}</math>
/=	Divides the target's score and the source's score, then applies the Template:W function on the result. <math>\text{New Target Score} = \left\lfloor \frac{\text{Target Score}}{\text{Source Score}} \right\rfloor</math>
%=	Applies the Template:W operation on the target's score and the source's score, returning the remainder of a division. <math>\text{New Target Score} = \text{Target Score} \mod \text{Source Score}</math>
=	Assigns the source's score as the new target's score without applying any other arithmetic operations whatsoever. <math>\text{New Target Score } = \text{ Source Score}</math>
<	Assigns the minimum value between the target's score and the source's score. It will compare and pick the lowest score value between the target's and the source's scores. <math>\text{New Target Score} = \min(\text{Target Score}, \text{Source Score})</math>
>	Assigns the maximum value between the target's score and the source's score. It will compare and pick the highest score value between the target's and the source's scores. <math>\text{New Target Score} = \max(\text{Target Score}, \text{Source Score})</math>
><	Swaps the target's score and the source's score. The target's score will be the source's score, and the source's score will be the target's score. <math>\text{Target Score } \leftrightarrow \text{ Source Score}</math>

For arithmetic operations, if there is more than one score holder specified as the sources, the game executes the operations once with each source's score, and if there is more than one target score holder, the game executes the operations for each target one by one.

These operations are available by using the scoreboard players sub-commands, e.g.

Template:Cmd for arithmetic operations,
Template:Cmd to set a target entity's score, and
Template:Cmd to test a target entity's score.Template:Only
- Template:IN, you'd use Template:Cmd and the Template:Cd target selector argument.

In Java Edition, modifying scores are also possible using Template:Cmd command, where the result of a command would be stored to the entity's score. Such commands like Template:Cmd results a random value that can be stored to the entity's scores.

Display slots

File:Scoreboard Display.png

An objective with two points to the player is displayed in the "list" slot, while an objective with the display name "Quest Points" with 0 points to the player is displayed in the "sidebar" slot.

File:Scoreboard setdisplay belowname.png

A scoreboard displayed below a player's name

An entity's scores in objectives can be displayed in certain slots in the game. These slots are called display slots, and they can appear in the player list, sidebar on the right side of the screen, below a player's name tag, etc. Each display slot can show one objective at a time, and multiple display slots may be used for the same or different objectives.

When players' scores appear on display slots, their Minecraft:username is used to attribute the score holder. For entities, their Minecraft:unique identifiers are used instead. The score holder's name on display slots can be specifically changed by using Template:Cmd.

Entities' scores can only be displayed on the sidebar slot, while other slots are exclusive for players.

Display slots can be set by Template:Cmd command.

Slot	Description
list	Displays a yellow number or some hearts (Template:Cmd) without the objective heading on the tab menu, where online players are shown.Template:Only Used to display score in the Minecraft:game menu Template:In but currently does nothing.<ref>Template:Bug</ref> Visible even in singleplayer.
sidebar	Shows on the right hand side of the screen, up to 15 entities with the highest score of that objective with a heading labeled with the objective's display name. Note that players are shown even if offline, and untracked players are not shown. In addition, fake players with names starting with a Template:Cd character do not show up in the sidebar under any circumstances.
Template:Nohtml Template:Only	There are 16 team-specific sidebar display slots. These operate the same as the standard sidebar slot, but display only to players who are on teams that use the specified color (for example, "sidebar.team.green" displays to players on "green" teams). The `<color>` is a color from the list: Template:Collapse
below_nameTemplate:Only belownameTemplate:Only	Shows the score followed by the objective's display name below the player's name tag above their head. This is hidden beyond around 10 blocks and when the player is Minecraft:sneaking. Not visible in singleplayer.

Teams

Template:Redirect Template:Exclusive

Teams group entities or players together as allies.

Any entity can only have a single team. Mobs do not intentionally attack other entities on the same team.

Teams have a name property, used internally for reference in commands, target arguments, and the file format. Like objectives, it is a single, case-sensitive string consisting of alphanumeric characters. Teams also have other several properties to set its appearances and behaviors:

Property	Description	Value
displayName	Sets the team's display name that appears on the scoreboard's display slots, such as the player list, below the player's name tag, and the sidebar.	Minecraft:Text component
color	Sets the team's color that appears on the player name in chat, name tag, player list menu, and on the scoreboard sidebar. It also changes the color of the entities outline caused by the Minecraft:Glowing effect.	{{#VAR:team_colors}}
collisionRule	Controls a member's collision rule with other team members, or their own.<ref group="note">Due to MC-87984, the behaviors of Template:Cd and Template:Cd are reversed.</ref>	`always` (default), Template:Cd
deathMessageVisibility	Controls a member's Minecraft:death message visibility with other team members, or their own.	`always` (default), Template:Cd
nametagVisibility	Controls a member's name tag visibility from other team members, or their own. Members' name tag is visible above the Minecraft:player head.	`always` (default), Template:Cd
friendlyFire	Toggles the team's friendly fire rule that controls if a member can attack other members on the same team. The attack damage can be from melee attack, bow and arrow, Minecraft:splash potion of Minecraft:Harming, and more. Note that team members may still inflict negative status effects on each other with potions, like with a splash potion of Minecraft:Poison.	{{#VAR:boolean_true}}
seeFriendlyInvisibles	Toggles a member's visibility to other members on the same team with Minecraft:Invisibility effect.	{{#VAR:boolean_true}}
prefix	Sets the team's prefix that appears before the member's name in the chat, name tag, and the player list menu.	Quoted string
suffix	Sets the team's suffix that appears after the member's name in the chat, name tag, and the player list menu.	Quoted string

Commands can be used to check whether team members exist by using target selection with the "team" argument. An exclamation point Template:Cd character may be placed before a team name to check for entities not on that team. For example, inputting Template:Cmd into a Minecraft:command block provides Minecraft:comparator output if any player exists on the red team. Conversely, Template:Cmd provides output when there are any players not on the red team. Template:Cmd allows output when at least one player is on any team, and Template:Cmd allows output when at least one player is on no team.

NBT format

Template:Exclusive The file scoreboard.dat in the data/minecraft folder of the world save folder stores the scoreboard data for that world as a Template:W compressed Minecraft:NBT file:

* Optional.

† Optional, with a default value when absent

‡ Optional, may be absent when empty

Template:Nbt The root tag.
- Template:Nbt: Minecraft:data version of the scoreboard NBT structure.
- Template:Nbt: The scoreboard data.
  - Template:Nbt^‡: A list of compound tags representing objectives.
    - Template:Nbt An objective.
      - Template:Nbt: The criterion of this objective.
      - Template:Nbt: The display name of this objective in JSON. If none was specified during the objective's creation, this is set to {"text":"Value of Name"}.
      - Template:Nbt: The internal name of this objective.
      - Template:Nbt^†: The way the score is displayed. Can be "integer" or "hearts". Defaults to "integer" when absent.
      - Template:Nbt^†: 1 or 0 (true/false) - Whether display names in the sidebar automatically update whenever score values change. Defaults to 0 (false) when absent.
      - Template:Nbt^*: The default number format for this objective. See Template:Sl.
  - Template:Nbt^‡: A list of compound tags representing scores tracked by the scoreboard system.
    - Template:Nbt A tracked player/objective pair with a score.
      - Template:Nbt: The score this player has in this objective.
      - Template:Nbt: The name of the player who has this score in this objective.
      - Template:Nbt: The internal name of the objective that this player has this score in.
      - Template:Nbt^†: 1 or 0 (true/false) - false if this objective is "enabled". Meaningful only for objectives with the criteria "trigger", where this must be false before a player can use the /trigger command on it. Defaults to 0 (false) when absent.
      - Template:Nbt^*: The text component used as display name in the sidebar.
      - Template:Nbt^*: The number format of the player score. See Template:Sl.
  - Template:Nbt^‡: A list of compound tags representing teams.
    - Template:Nbt A Team.
      - Template:Nbt: 1 or 0 (true/false) - true if players on this team can harm each other.
      - Template:Nbt: 1 or 0 (true/false) - true if players on this team can see invisible teammates.
      - Template:Nbt: The value of the nametagVisibility option of this team.
      - Template:Nbt: The value of the deathMessageVisibility option of this team. Valid options are: never, hideForOtherTeams, hideForOwnTeam, always
      - Template:Nbt: The value of the collisionrule option of this team. Valid options are: always, pushOwnTeam, never, pushOtherTeams
      - Template:Nbt: The display name of this team in JSON. If none was specified during the team's creation, this is set to {"text":"Value of Name"}.
      - Template:Nbt: The internal name of this team.
      - Template:Nbt: The prefix prepended to names of players on this team. In JSON format.
      - Template:Nbt: The suffix appended to names of players on this team. In JSON format
      - Template:Nbt^*: The text-based color given to the team. Does not exist if no color is set.
      - Template:Nbt: A list of names of players on this team.
        Template:Nbt The name of a player on this team.
  - Template:Nbt^‡: A set of slots that display specific objectives, see below. If a slot is empty, its tag is not present.
    - Template:Nbt: Player list.
    - Template:Nbt: On the siderbar.
    - Template:Nbt: Below the player's username.
    - Template:Nbt: Sidebar categorized by team colors.
    - Additionally, if the display slot used old numerical values (see the table below), it will be renamed into the current values.<ref>Template:Jcp</ref>

Numerical display slots
No.	Type	Name
0	Player list	list
1	On the sidebar	sidebar
2	Below the player's username	below_name
3	Team color	sidebar.team.black
4		sidebar.team.dark_blue
5		sidebar.team.dark_green
6		sidebar.team.dark_aqua
7		sidebar.team.dark_red
8		sidebar.team.dark_purple
9		sidebar.team.gold
10		sidebar.team.gray
11		sidebar.team.dark_gray
12		sidebar.team.blue
13		sidebar.team.green
14		sidebar.team.aqua
15		sidebar.team.red
16		sidebar.team.light_purple
17		sidebar.team.yellow
18		sidebar.team.white