![]() |
VOOZH | about |
The scoreboard system is a complex gameplay mechanic utilized through commands. Mainly intended for mapmakers and server operators, scoreboards are used to track, set, and list the scores of entities in a myriad of different ways.
An objective tracks a score for entities while meeting a single criterion. These scores are stored as 32-bit integer ranging from -231 to 231-1.[a]
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.
In Java Edition, the objectives' name must be a single, case-sensitive string consisting of alphanumeric characters (AβZ and 0β9), hyphen -, plus +, dot ., and underscore _. In Bedrock Edition, it must either be a single string that has no space or a quoted string. When a string is quoted, backslash \ 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 Β§ Criteria). 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 /scoreboard and /execute store (the latter is exclusive to Java Edition only).
The score holder's name can either be the player's username or the entity's UUID. For players, the score holder's name doesn't need to belong to an actual player, and can be specified by any arbitrary username. As player names cannot contain spaces, a figure space β (U+2007) can be used as a visually identical substitute instead.
Objectives also have other properties to change its appearance and behavior:
| 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. | Text component |
| numberformat | The objective's number format for the score. The value can be blank, fixed, or styled.
|
|
| 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.
|
|
| displayautoupdate | Whether or not to display auto updates when the score has changed. | Boolean: true (default) or false
|
The number format property and the score holder's name can be changed per-entity using /scoreboard players display numberformat|name <target> ....
Server operators can select entities by their scores using 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 /execute if entity @a[scores={deaths=1..}] into a command block triggers a 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.
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.
In Java Edition, criteria are categorized by single and compound criteria. Each of the criteria tracks specific game elements, such as players' health, hunger, experience, triggers, statistics, and among other things. In Bedrock Edition, the "dummy" criterion is the only criteria supported. As such, scores can only be changed by commands.
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. | Yes |
| trigger | A score that can be changed by commands and not automatically by the game. The /trigger 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 /trigger command, even if cheats are disabled or they are not server operators, making it useful for safely taking input from non-operator players.
|
Yes |
| deathCount | The score increments automatically when a player dies. | Yes |
| playerKillCount | The score increments automatically when a player kills another player. | Yes |
| totalKillCount | The score increments automatically when a player kills another player or a mob. | Yes |
| 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 attributes, Health Boost or Absorption effects. | No |
| xp | Matches the total amount of experience the player has collected since their last death. | No |
| level | Matches the current experience level of the player. | No |
| 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. | No |
| air | Ranges from 0 to 300; represents the amount of air a player has left while swimming underwater. It matches the air NBT tag of the player. | No |
| 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. | No |
Compound criteria names are divided into parts, delimited with periods .. For example, minecraft.killed_by:minecraft.zombie 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.
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:
| 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 Team colors
black, dark_blue, dark_green, dark_aqua, dark_red, dark_purple, gold, gray, dark_gray, blue, green, aqua, red, light_purple, yellow, and white
|
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 Team colors
black, dark_blue, dark_green, dark_aqua, dark_red, dark_purple, gold, gray, dark_gray, blue, green, aqua, red, light_purple, yellow, and white
|
16 |
Players can increment, decrement, reset and modify an entity's scores by a specific amount using commands. They can also set scores to a 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:
Below is a list of available arithmetic operations.
| Operation | Description |
|---|---|
| += | Adds the target's score and the source's score. |
| -= | Subtracts the target's score and the source's score. |
| *= | Multiplies the target's score and the source's score. |
| /= | Divides the target's score and the source's score, then applies the floor function on the result. |
| %= | Applies the modulo operation on the target's score and the source's score, returning the remainder of a division. |
| = | Assigns the source's score as the new target's score without applying any other arithmetic operations whatsoever. |
| < | 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. |
| > | 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. |
| >< | 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. |
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.
/scoreboard players operation <targets> <targetObjective> <operation> <source> <sourceObjective> for arithmetic operations,/scoreboard players set <targets> <objective> <score> to set a target entity's score, and/scoreboard players test <player: target> <objective: string> <min: wildcard int> [<max: wildcard int>] to test a target entity's score.β[Bedrock Edition only]
/execute if <targets> and the [scores={<objective>=<min>..<max>}] target selector argument.In Java Edition, modifying scores are also possible using /execute store result score command, where the result of a command would be stored to the entity's score. Such commands like /random results a random value that can be stored to the entity's scores.
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 username is used to attribute the score holder. For entities, their unique identifiers are used instead. The score holder's name on display slots can be specifically changed by using /scoreboard players display name <target> <objective> [<name>].
Entities' scores can only be displayed on the sidebar slot, while other slots are exclusive for players.
Display slots can be set by /scoreboard objectives setdisplay <slot> [<objective>] command.
| Slot | Description |
|---|---|
| list | Displays a yellow number or some hearts (/scoreboard objectives modify <objective> rendertype (hearts|integer)) without the objective heading on the tab menu, where online players are shown.β[Java Edition only]
Used to display score in the game menu in Bedrock Edition but currently does nothing.[1] 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 |
| sidebar.team.<color> β[Java Edition 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 Team colors
black, dark_blue, dark_green, dark_aqua, dark_red, dark_purple, gold, gray, dark_gray, blue, green, aqua, red, light_purple, yellow, and white
|
| below_nameβ[Java Edition only]
belownameβ[Bedrock Edition 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 sneaking. Not visible in singleplayer. |
Tags are a simple list of single-word strings stored directly in the [NBT List / JSON Array] Tags data of an entity, with maximum limit of 1024 tags. As with objectives, tags are case-sensitive.
Target selectors can be used to check whether an entity has a tag with the "tag" argument.
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. | 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 Glowing effect. | black, dark_blue, dark_green, dark_aqua, dark_red, dark_purple, gold, gray, dark_gray, blue, green, aqua, red, light_purple, yellow, and white
|
| collisionRule | Controls a member's collision rule with other team members, or their own.[note 1] | always (default), never, pushOtherTeams, and pushOwnTeam
|
| deathMessageVisibility | Controls a member's death message visibility with other team members, or their own. | always (default), never, hideForOtherTeams, and hideForOwnTeam
|
| nametagVisibility | Controls a member's name tag visibility from other team members, or their own. Members' name tag is visible above the player head. | always (default), never, hideForOtherTeams, and hideForOwnTeam
|
| 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, splash potion of Harming, and more. Note that team members may still inflict negative status effects on each other with potions, like with a splash potion of Poison. | Boolean: true (default) or false
|
| seeFriendlyInvisibles | Toggles a member's visibility to other members on the same team with Invisibility effect. | Boolean: true (default) or false
|
| 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 ! character may be placed before a team name to check for entities not on that team. For example, inputting /execute if entity @a[team=red] into a command block provides comparator output if any player exists on the red team. Conversely, /execute if entity @a[team=!red] provides output when there are any players not on the red team. /execute if entity @a[team=!] allows output when at least one player is on any team, and /execute if entity @a[team=] allows output when at least one player is on no team.
The file scoreboard.dat in the data/minecraft folder of the world save folder stores the scoreboard data for that world as a gzip compressed NBT file:
{"text":"Value of Name"}.{"text":"Value of Name"}.| 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 |
Objectives and individual players can have their display formatted.
The possible values for [String] type and associated extra fields are listed below.
| Java Edition | |||||||
|---|---|---|---|---|---|---|---|
| 1.5 | 13w04a | Added scoreboard. | |||||
| 13w05a | Added team-based functionality. | ||||||
| 1.7.2 | 13w36a | Added statistic-based objective criteria. | |||||
| 1.8 | 14w02a | Entities other than players can now be part of teams and have objective scores. | |||||
| 14w06a | Added the trigger and team kill-based objective criteria.
| ||||||
Added /scoreboard players enable.
| |||||||
| "*" can be used in a player name argument to represent all players tracked by the scoreboard. | |||||||
Added the "objective" argument to /scoreboard players reset.
| |||||||
| Statistic objective criteria now use named IDs instead of numerical IDs. | |||||||
Added the achievement.overpowered objective criterion. | |||||||
| 14w07a | Added /scoreboard players operation and /scoreboard players test.
| ||||||
| Scores for fake players that have a name beginning with "#" don't appear in the sidebar. | |||||||
| Added team-specific sidebar display slots. | |||||||
Added the nametagVisibility team option. | |||||||
| 14w10a | Added the deathMessageVisibility team option.
| ||||||
Added a dataTag argument to /scoreboard players set, /scoreboard players add, and /scoreboard players remove.
| |||||||
Added the stat.crouchOneCm, stat.sprintOneCm, and stat.timeSinceDeath objective criteria. | |||||||
| 14w25a | Added =, <, and > to /scoreboard players operation. | ||||||
| 14w29a | Player/entity names in the sidebar are now secondarily sorted by alphabetical order. | ||||||
| 14w30a | Added the stat.talkedToVillager and stat.tradedWithVillager objective criteria. | ||||||
| ? | Added >< to /scoreboard players operation. | ||||||
| 1.8.2 | Added the stat.cauldronFilled, stat.cauldronUsed, stat.armorCleaned, stat.bannerCleaned, stat.brewingstandInteraction, stat.beaconInteraction, stat.dropperInspected, stat.hopperInspected, stat.dispenserInspected, stat.noteblockPlayed, stat.noteblockTuned, stat.flowerPotted, stat.trappedChestTriggered, stat.enderchestOpened, stat.itemEnchanted, stat.recordPlayed, stat.furnaceInteraction, stat.craftingTableInteraction, stat.chestOpened objective criteria. | ||||||
| 1.9 | 15w32a | Added the stat.sneakTime objective criteria. | |||||
| 15w32b | Added /scoreboard players tag.
| ||||||
Added the xp, food, and air objective types. | |||||||
| 15w33a | Added the stat.pickup and stat.drop objective criteria.
| ||||||
Added the armor, level objective types. | |||||||
| 15w36a | Added collisionRule. | ||||||
| 15w49a | Added the stat.aviateOneCm objective criteria. | ||||||
| 1.13 | pre7 | Added /scoreboard objectives modify. | |||||
| pre8 | Added /scoreboard objectives modify <objectiveName> rendertype hearts, which makes health bars display as hearts, like this: π β€οΈπ β€οΈ π β€οΈ π β€οΈ π β€οΈ π β€οΈ π π€ π π€ π π€ π π€ . | ||||||
Added /scoreboard objectives modify <objectiveName> rendertype integer, which makes health bars display as yellow numbers.
| |||||||
| Objective names are now text components, not raw strings. | |||||||
| 1.13.1 | 18w31a | Changed the scoreboard operator %= from using % to Math.floorMod. | |||||
| 1.18 | 21w37a | Removed 16-character length limits for scoreboards, score holders and team names. | |||||
| 1.20.2 | 23w31a | The belowName display slot selector is now below_name. | |||||
| 1.20.3 | 23w46a | Added display_auto_update and format to each objective, and display and type to player entries. | |||||
| 26.2 | snap5 | A player's score will no longer be displayed in the player tab overlay if the player doesn't have the objective. | |||||
| Bedrock Edition | |||||||
|---|---|---|---|---|---|---|---|
| 1.7.0 Experiment | beta 1.7.0.2 | Added basic scoreboard mechanics. | |||||
| Added dummy scoreboards. | |||||||
| Both are currently only available with Experimental Gameplay enabled. | |||||||
| 1.7.0 | beta 1.7.0.7 | Scoreboard functionality is now available outside of Experimental Gameplay. | |||||
Issues relating to "Scoreboard" are maintained on the bug tracker. Issues should be reported and viewed there.