A screenshot of a scoreboard on the right side of the screen.
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.
Objectives[]
Objectives each have three main variables: A name, a criterion, and a display name. Objectives track a number of points for entities, and are stored and displayed as integers with a full score range of -2,147,483,648 to 2,147,483,647.
An objective's name is used internally for referencing in commands, target arguments, and the file format. In Java Edition, the allowed character set for it includes all lowercase and uppercase letters, numbers, underscore, period, minus and plus. In Bedrock Edition, it can contain any character.
An objective's display name is a raw JSON text and is displayed publicly in various situations. It does not have to be unique.
An objective's criterion determines its behavior—primarily what to track. Lists of valid criteria are provided below.
An entity's score in any objective can be changed via commands unless it's read-only (see #Criteria). It can be increased by, decreased by, or set to a given amount with commands.
A score holder is a player's name or an entity's UUID that has scores in an objective. The player name doesn’t need to belong to an actual player. Scores of non-player entities can be changed only by commands, and not by game system. Unlike players, when a non-player entity dies, its scores are deleted.
Commands can check entity scores by using target selector with the scores argument (syntaxed @e[scores={<name>=<min>..<max>}]. This argument uses <name> to specify the internal name of the tested-for objective.
- For example, in Java Edition, 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, assuming "deaths" is an objective of the "deathCount" criterion.
Criteria[]
Java Edition[]
Single criteria[]
- These criteria's names consist of a single alphabetical string.
Criterion name Description Can be modified dummy Score is only changed by commands, and not by game events such as death. This is useful for event flags, state mappings, currencies,... Yes trigger Score is only changed by commands, and not by game events such as death. The /triggercommand can be used by a player to set or increment/decrement their own score in an objective with this criterion. The/triggercommand fails if the objective has not been "enabled" for the player using it, and the objective is disabled for the player after using the/triggercommand on it. Note that the/triggercommand can be used by ordinary players even if Cheats are off and they are not an Operator. This is useful for player input via/tellrawinterfaces.Yes deathCount Score increments automatically for a player when they die. Yes playerKillCount Score increments automatically for a player when they kill another player. Yes totalKillCount Score increments automatically for a player when they kill another player or a mob. Yes health Ranges from 0 to 20 on a normal player; represents the amount of half-hearts the player has. May appear as 0 for players before their health has changed for the first time. Extra hearts and absorption hearts also count to the health score, meaning that with Attributes/Modifiers or the Health Boost or Absorption status effects, health can far surpass 20. No xp Matches the total amount of experience the player has collected since their last death (or in other words, their score). No level Matches the current experience level of the player. No food Ranges from 0 to 20; represents the amount of hunger points the player has. May appear as 0 for players before their foodLevel has changed for the first time. No air Ranges from 0 to 300; represents the amount of air the player has left from swimming under water, matches the air nbt tag of the player. No armor Ranges from 0 to 20; represents the amount of armor points the player has. May appear as 0 for players before their armor has changed for the first time. No
Compound criteria[]
- Compound criteria's names are divided into parts, delimited with periods (.). For example,
minecraft.killed_by:minecraft.zombieis a valid compound criterion, under which player scores would increment whenever they're killed by zombie.
- All objectives based on compound criteria is writable and can be modified with commands.
- All statistics can be used as a compound criterion whose name is its identifier. Player statistics are stored separately from the scoreboard, and as they update, scores in these objectives are updated in parallel.
- In addition, there are some other compound criteria:
| Criteria base name | Description | Number of sub-criteria | ||
|---|---|---|---|---|
| teamkill. | 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
|
16 | ||
| killedByTeam. | Sub-criteria include team colors. Player scores increment when a player has been killed by a member of the given colored team.
These criteria follow the complete format
|
16 |
Bedrock Edition[]
Currently, dummy is the only criterion supported. As such, score can only be changed by commands.
Display slots[]
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.
Via the /scoreboard objectives setdisplay command (see command reference), players' scores in specific objectives can be displayed in certain 'slots' in-game. Each 'display slot' can show one objective at a time, and multiple 'display slots' may be used for the same or different objectives.
| Slot | Description |
|---|---|
| list | Displays a yellow number or some hearts (/scoreboard objectives modify <objective> rendertype (hearts|integer)) without a heading on the tab menu, where online players are shown.[Java Edition only]
Displays a white number without a heading on the Pause Menu, where online players are shown.[Bedrock Edition only] Visible even in singleplayer. |
| sidebar | Shows on the right hand side of the screen. Shows up to 15 entities with the highest score of that objective with a heading labeled with the objective's <DisplayName>. Note that players are shown even if offline, and untracked players are not shown. In addition, fake players with names starting with a # do not show up in the sidebar under any circumstances. |
| sidebar.team.<color> [Java Edition only] | There are 16 team-specific sidebar display slots. These operate the same as the standard sidebar slot, but only display to players who are on teams which use the specified color (for example, "sidebar.team.green" displays to players on "green" teams). Valid colors are: "black", "dark_blue", "dark_green", "dark_aqua", "dark_red", "dark_purple", "gold", "gray", "dark_gray", "blue", "green", "aqua", "red", "light_purple", "yellow", "white". |
| belowName | Shows the <Score> followed by the objective's <DisplayName> below the player's nametag above their head. This is hidden beyond ~10 blocks and when the player is sneaking. Not visible in singleplayer. |
Tags[]
Tags are a simple list of single-word strings stored directly in the Tags data tag of an entity. 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[]
A team's all variables are: a name, a display name, a member name prefix, a member name suffix, a boolean allow friendly fire option, and a list of players who are on the team.
A team's Name is used internally for reference in commands, target arguments, and the file format. It is a single, case-sensitive word.
A team's DisplayName is a JSON text component of one or more case-sensitive word, and is displayed publicly in various situations.
A team's Member Name Prefix & Member Name Suffix are inserted before and after the names of players on the team, respectively. Prefixes and suffixes are used in the chat, the active players list, the sidebar, and above team members' heads. These can be edited with respective commands.
The AllowFriendlyFire option controls whether or not members of a team are able to damage each other. This defaults to true, leaving PvP mechanics unchanged—ergo, players can harm their teammates. When set to false, however, players on the same team are prevented from directly damaging each other with melee attacks, bows, and Splash Potions of Harming. Note that players on the same team may still inflict negative status effects on each other with potions, even if <AllowFriendlyFire> is false. Some non-player entities in a team are also affected by this.
It is important to note that each individual team member can only be on one team; teams cannot share entities.
Commands can be used to check whether team members exist by using target selection with the "team" argument. (The '!' character may be placed before a name to check for entities not on a 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 no players on the red team. /execute if entity @a[team=!] allows output when any player is on at least one team, and /execute if entity @a[team=] allows output when no players are on any teams.
Command reference[]
For more details, see Commands/scoreboard.
Objectives commands[]
| Commands | Description |
|---|---|
| scoreboard objectives list | List all existing objectives with their display names and criteria. |
| scoreboard objectives add <objective> <criteria> [<displayName>][Java Edition only] scoreboard objectives add <objective: string> dummy [displayName: string][Bedrock Edition only] |
Create a new objective with the given internal objective name, specified criterion, and the optional display name. In Bedrock Edition, "dummy" is the only criterion currently supported. <displayName> defaults to <objective> when unspecified. See above section for more on these arguments.
|
| scoreboard objectives remove <objective>[Java Edition only] scoreboard objectives remove <objective: string>[Bedrock Edition only] |
Delete all references to the named objective in the scoreboard system. Data is deleted from the objectives list and score holders' scores, and if it was on a display list it is no longer displayed. |
| scoreboard objectives setdisplay <slot > [<objective ][Java Edition only] scoreboard objectives setdisplay <list|sidebar> [objective: string] [ascending|descending][Bedrock Edition only] scoreboard objectives setdisplay belowname [objective: string][Bedrock Edition only] |
Display score info for the objective in the given slot. Valid slots are listed and described in Display Slots. In Bedrock Edition, if slot is list or sidebar, there is an additional optional argument ascending|descending to specify the sort order. Note that the objective parameter is optional; if no objective is provided, this display slot is cleared (returned to its default state).
|
| scoreboard objectives modify <objective> displayname <displayName> [Java Edition only] | Change the display name of the scoreboard in display slots. |
| scoreboard objectives modify <objective> rendertype (hearts|integer) [Java Edition only] | Change the display format of the player list. |
Players commands[]
| Commands | Description |
|---|---|
| scoreboard players list [<target>][Java Edition only] scoreboard players list [playername: target][Bedrock Edition only] |
Lists all score holders which are tracked in some way by the scoreboard system. The optional <target> or playername: target parameter is used to list the scores of particular score holders.
|
| scoreboard players get <target> <objective> [Java Edition only] | Return the scoreboard value. |
| scoreboard players set <targets> <objective> <score>[Java Edition only] scoreboard players set <player: targets> <objective: string> <count: int>[Bedrock Edition only] |
Set the targets' scores of the given objective, overwriting any previous score. |
| scoreboard players add <targets> <objective> <score>[Java Edition only] scoreboard players add <player: targets> <objective: string> <count: int>[Bedrock Edition only] |
Increments the targets' scores in that objective by the given amount. |
| scoreboard players remove <targets> <objective> <score>[Java Edition only] scoreboard players remove <player: targets> <objective: string> <count: int>[Bedrock Edition only] |
Decrements the targets' scores in that objective by the given amount. |
| scoreboard players random <player: target> <objective: string> <min: int> <max: int> [Bedrock Edition only] | Sets the targets' scores in that objective to a random number between min and max, both inclusive. |
| scoreboard players reset <targets> [<objective>][Java Edition only] scoreboard players reset <player: target> [objective: string][Bedrock Edition only] |
Deletes score or all scores for the target. If <objective> is specified, then only that objective is cleared. Otherwise, this applies to all objectives. Note that this does not merely set the score(s) to 0: it removes the targets from the scoreboard altogether (or for the given objective).
|
| scoreboard players test <player: target> <objective: string> <min: wildcard int> [<max: wildcard int>] [Bedrock Edition only] | Tests if targets' scores are within min: wildcard int and max: wildcard int (Defaults to 2,147,483,647). min: wildcard int can be replaced with asterisk (*) to represent -2,147,483,648, and max: wildcard int can be replaced with asterisk (*) to represent 2,147,483,647.
|
| scoreboard players enable <targets> <objective> [Java Edition only] | Enables the target player(s) to use the /trigger command on the specified objective. This command accepts non-player entities, but only players are able to actually use the /trigger command. Until this has been done, players that attempt to /trigger that objective fail. Using the /trigger command disables it again. Note that if the target(s) did not previously have a score for the specified objective, this command will set their score to 0.
|
| scoreboard players operation <targets> <targetObjective> <operation> <source> <sourceObjective>[Java Edition only] scoreboard players operation <player: target> <targetObjective: string> <operation: operator> <selector: target> <objective: string>[Bedrock Edition only] |
Applies an arithmetic operation altering the targets' score(s) in the target objective, using sources' scores in the source objective as input.
<operation> may be:
In all cases except "><", source's score remains unchanged. If target or source isn't tracked by the specified objective, it will be set to 0. If more than one score holder is specified as sources, performs the operation once with each source's score. If more than one target score holder is specified, performs the operation for each target one by one. |
Tags commands[]
Teams commands[]
NBT format[]
The file scoreboard.dat in the 'data' folder of a Minecraft world stores the scoreboard data for that world as a GZip'd NBT file:
- The root tag.
- data: The scoreboard data.
- Objectives: A list of compound tags representing objectives.
- An objective.
- CriteriaName: The criterion of this objective.
- DisplayName: 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"}. - Name: The internal name of this objective.
- RenderType: The way the score is displayed. Can be "integer" or "hearts", but defaults to "integer".
- An objective.
- PlayerScores: A list of compound tags representing scores tracked by the scoreboard system.
- A tracked player/objective pair with a score.
- Score: The score this player has in this objective.
- Name: The name of the player who has this score in this objective.
- Objective: The internal name of the objective which this player has this score in.
- Locked: 1 or 0 (true/false) - false if this objective is "enabled". Only meaningful for objectives with the criteria "trigger", where this must be false before a player can use the /trigger command on it.
- A tracked player/objective pair with a score.
- Teams: A list of compound tags representing teams.
- A Team.
- AllowFriendlyFire: 1 or 0 (true/false) - true if players on this team can harm each other.
- SeeFriendlyInvisibles: 1 or 0 (true/false) - true if players on this team can see invisible teammates.
- NameTagVisibility: The value of the nametagVisibility option of this team.
- DeathMessageVisibility: The value of the deathMessageVisibility option of this team. Valid options are: never, hideForOtherTeams, hideForOwnTeam, always
- CollisionRule: The value of the collisionrule option of this team. Valid options are: always, pushOwnTeam, never, pushOtherTeams
- DisplayName: 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"}. - Name: The internal name of this team.
- MemberNamePrefix: The prefix prepended to names of players on this team. In JSON format.
- MemberNameSuffix: The suffix appended to names of players on this team. In JSON format
- TeamColor: The text-based color ("black", "dark_blue", etc.) given to the team. Does not exist if no color is set.
- Players: A list of names of players on this team.
- The name of a player on this team.
- A Team.
- DisplaySlots: A set of slots which are displaying specific objectives. If a slot is empty, its tag is not present.
- slot_n: The internal name of the objective displayed (see below).
- Objectives: A list of compound tags representing objectives.
- data: The scoreboard data.
| No. | Type | Name |
|---|---|---|
| 0 | Player list | list |
| 1 | On the sidebar | sidebar |
| 2 | Below the player's username | belowName |
| 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 |
History[]
| 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 "#" won'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. | |||
| Upcoming Java Edition | |||||
| 1.20.2 | 23w31a | The belowName display slot selector is now below_name. | |||
| Bedrock Edition | |||||
| 1.7.0 | beta 1.7.0.2 | Added basic scoreboard mechanics. | |||
| Added dummy scoreboards. | |||||
Issues[]
Issues relating to "Scoreboard" are maintained on the bug tracker. Report issues there.
Gallery[]
A "dirt dug" scoreboard.
A "pigs killed" scoreboard.
A "deaths by zombie" scoreboard.
A long list of scoreboard objectives.
References[]
