Scoreboards, storage & NBT

The integer-only scoreboard system, command storage as a datapack database, the NBT/SNBT data model, and the execute store bridge and macros that tie them together — the numeric and structured-data backbone of Java-Edition datapacks (primary target 1.21+).

Scoreboard system

A scoreboard objective tracks a 32-bit signed integer score per score holder. Scores range from -2,147,483,648 to 2,147,483,647. A score holder is a player username, an entity UUID, or an arbitrary string called a fake player. Every objective has exactly one criterion that defines how the game may change it automatically — or dummy/trigger, which the game never touches on its own.

Objective names may contain alphanumerics plus -, +, ., _. Historically these were capped at 16 characters; modern versions are more lenient, but keep names short and machine-safe.

Full /scoreboard syntax

Objectives

scoreboard objectives list
scoreboard objectives add <objective> <criterion> [<displayName>]
scoreboard objectives remove <objective>
scoreboard objectives setdisplay <slot> [<objective>]        # omit objective to clear the slot
scoreboard objectives modify <objective> displayname <component>
scoreboard objectives modify <objective> rendertype (hearts|integer)
scoreboard objectives modify <objective> displayautoupdate <true|false>   # 1.20.3+
scoreboard objectives modify <objective> numberformat blank               # 1.20.3+
scoreboard objectives modify <objective> numberformat fixed <component>   # 1.20.3+
scoreboard objectives modify <objective> numberformat styled <style>      # 1.20.3+

Players (score holders)

scoreboard players list [<target>]
scoreboard players get <target> <objective>
scoreboard players set <targets> <objective> <score>
scoreboard players add <targets> <objective> <amount>
scoreboard players remove <targets> <objective> <amount>
scoreboard players reset <targets> [<objective>]         # reset removes the score entirely (not =0)
scoreboard players enable <targets> <objective>          # only meaningful for 'trigger' objectives
scoreboard players operation <targets> <targetObj> <op> <source> <sourceObj>
scoreboard players display name <targets> <objective> [<component>]                                  # per-holder display name
scoreboard players display numberformat <targets> <objective> (blank|fixed <c>|styled <style>)        # 1.20.3+

Operations

The operation subcommand takes an operator <op> that combines a target score with a source score.

Criteria (Java Edition)

Every objective is created with one criterion. Single (non-statistic) criteria:

Team-color criteria — each has 16 color variants (black, dark_blue, … white):

Statistic (compound) criteria — any tracked statistic can be a live objective that increments automatically as the underlying statistic changes. The general form is:

minecraft.<category>:<namespaced statistic id>

Categories map to the statistics registry:

custom:<stat> is the shorthand often written for minecraft.custom:minecraft.<stat>. Because these objectives increment live, a datapack can detect the change and reset the score to act on it — the common "on right-click carrot-on-a-stick" detection pattern.

Display slots

Objectives are shown in a display slot via scoreboard objectives setdisplay <slot>:

• sidebar — the right-hand HUD list.
• list — the tab player-list menu (Java only).
• below_name — under each entity's name tag.
• sidebar.team.<color> — 16 team-specific sidebar slots. Each shows its objective only to players whose team color matches, enabling per-team HUDs.

Number formats & display names

Objectives (and per-holder scores) can restyle how the number renders 1.20.3+:

• numberformat blank — hide the number entirely.
• numberformat fixed <component> — replace the number with a fixed text component (e.g. "★").
• numberformat styled <style> — keep the number but apply a style object such as {"color":"gold","bold":true}.
• displayautoupdate <bool> — whether the sidebar re-sorts/redraws live when scores change.
• Per-holder overrides via scoreboard players display name/numberformat take precedence over the objective's own setting.

The <component> and <style> arguments are raw-JSON text components. For the full component grammar (colors, formatting, events), see Text components & raw JSON.

Examples

data/<namespace>/function/load.mcfunction — objective setup + a styled sidebar

# in a load function
scoreboard objectives add coins dummy {"text":"Coins","color":"gold"}
scoreboard objectives modify coins numberformat styled {"color":"yellow"}
scoreboard objectives setdisplay sidebar coins
scoreboard players set @a coins 0

data/<namespace>/function/detect_jump.mcfunction — detect a jump via a live stat criterion

scoreboard objectives add jumped minecraft.custom:minecraft.jump
# each tick: if a player's jump count changed, do something then reset
execute as @a[scores={jumped=1..}] run function ns:on_jump
scoreboard players reset @a jumped   # or 'set ... 0'; reset avoids leftover holders

The trigger criterion & /trigger

/trigger is the only score-changing command a non-operator (permission level 0) player may run — and only on objectives with the trigger criterion that have been enabled for that specific player. This makes it the standard mechanism for player-invokable actions (menus, "claim reward", vote buttons) in permission-locked survival/adventure worlds.

Full syntax

trigger <objective>              # +1
trigger <objective> add <value>  # +value
trigger <objective> set <value>  # = value

The enable/consume cycle

1. Op/datapack creates the objective: scoreboard objectives add menu trigger.
2. Enable it per player: scoreboard players enable @a menu. Until enabled, /trigger menu errors for that player.
3. Player runs /trigger menu (or /trigger menu set 3). This auto-disables the objective for that player immediately after one use.
4. A datapack polls the score, acts on it, resets it, and re-enables the trigger for the next use.

So each /trigger fires exactly once per enable — you must re-enable every cycle.

Complete pattern example

data/ns/function/menu/open.mcfunction — sends a clickable menu

tellraw @s ["",{"text":"[ Teleport to spawn ]","color":"aqua","clickEvent":{"action":"run_command","command":"/trigger menu set 1"}},"\n",{"text":"[ Get a kit ]","color":"green","clickEvent":{"action":"run_command","command":"/trigger menu set 2"}}]
scoreboard players enable @s menu

data/ns/function/menu/poll.mcfunction — runs every tick (from #minecraft:tick)

execute as @a[scores={menu=1}] at @s run function ns:menu/tp_spawn
execute as @a[scores={menu=2}] at @s run function ns:menu/give_kit
# consume + re-arm anyone who used it
execute as @a[scores={menu=1..}] run scoreboard players enable @s menu
scoreboard players reset @a menu

Data storage & the /data command

/data reads and writes NBT on three target kinds:

• block <x y z> — a block entity (chest, sign, command block, barrel…).
• entity <selector> — a single entity's NBT (the selector must resolve to exactly one).
• storage <namespace:path> — command storage: free-form, persistent, namespaced NBT that belongs to no entity or block. This is the datapack "database"; it persists in the save and survives chunk unloading.

Requires permission level 2 (Java-only command).

Full syntax

data get    (block <pos> | entity <target> | storage <id>) [<path>] [<scale>]
data merge  (block <pos> | entity <target> | storage <id>) <nbt compound>
data remove (block <pos> | entity <target> | storage <id>) <path>
data modify (block <pos> | entity <target> | storage <id>) <path> <operation> <source>

Modify operations

Modify sources

Used by set/merge/append/prepend/insert:

value <snbt>                                                                       # a literal NBT value
from   (block <pos>|entity <t>|storage <id>) [<sourcePath>]                         # copy a value
string (block <pos>|entity <t>|storage <id>) [<sourcePath>] [<start>] [<end>]       # 1.19.4+: substring a string

• value inserts a literal SNBT tag.
• from copies the tag found at sourcePath (whole compound, list element, number, etc.).
• string reads a string tag and inserts a substring [start, end); negative indices count from the end; omit end to run to the string's end. 1.19.4+

The get scale

data get ... <path> <scale> multiplies the numeric result by <scale>, then floors it. This reads a fractional NBT value into a printable/int-usable form (and historically was used to get command return values). With no <scale>, numbers return as-is and lists/compounds return their length/size.

Examples

data/ns/function/db/demo.mcfunction — storage as a scratch database

# write
data modify storage ns:db player.lastLogin set value 1720000000L
data modify storage ns:db player.name set value "Steve"
# read (prints to chat / can be captured)
data get storage ns:db player
# remove
data remove storage ns:db player.lastLogin

data/ns/function/db/log_item.mcfunction — copy an entity's held item into storage, then append to a log list

data modify storage ns:db lastItem set from entity @s SelectedItem
data modify storage ns:log entries append from storage ns:db lastItem

data/ns/function/db/prefix.mcfunction — substring (1.19.4+): take first 3 chars of a stored string

data modify storage ns:db prefix set string storage ns:db player.name 0 3

data/ns/function/sign/edit.mcfunction — edit block-entity NBT (put custom text on a sign)

data merge block ~ ~1 ~ {front_text:{messages:['"Line 1"','""','""','""']}}

NBT format, SNBT & NBT paths

NBT (Named Binary Tag) is Minecraft's typed tree data format. In commands you write it as SNBT (Stringified NBT) — a JSON-like syntax where numeric types carry a type suffix.

Tag types & SNBT suffixes

Quoting rules: a key or string may be unquoted if it contains only 0-9 A-Z a-z _ - . +. Otherwise quote it. If the string contains ", use '...' (and vice-versa). Escape with \", \', \\, \n, \t, etc.

Number niceties (modern parsers): hex 0xFF, binary 0b1010, scientific 1.2e3, and _ digit separators (1_000_000) are accepted. Bare decimals are doubles; you must add f for float.

NBT paths

A path navigates into a tag. Building blocks:

A concrete deep example:

Items[{Slot:0b}].components."minecraft:written_book_content".pages[3].raw

Filters ([{...}], {...}) are also how execute if data tests existence:

execute if data entity @s Inventory[{id:"minecraft:diamond"}] run say has a diamond

Examples

data/ns/function/nbt/write.mcfunction — write nested custom data on an entity

data modify entity @s data set value {faction:"red",level:3,perks:["speed","haste"]}

data/ns/function/nbt/read.mcfunction — read one list element with a filter

data get entity @s Inventory[{Slot:0b}].count

execute store — bridging NBT and scores

Scoreboards hold ints; NBT holds typed numbers, strings, lists, compounds. execute store is the bridge: it captures a command's result (its numeric return) or success (0/1) and writes it into a score, storage/block/entity NBT, or bossbar.

Full syntax

execute store (result|success) score   <targets> <objective>                                                  ... run <command>
execute store (result|success) storage <id>     <path> (byte|short|int|long|float|double) <scale>            ... run <command>
execute store (result|success) block   <pos>    <path> (byte|short|int|long|float|double) <scale>            ... run <command>
execute store (result|success) entity  <target> <path> (byte|short|int|long|float|double) <scale>            ... run <command>
execute store (result|success) bossbar <id> (value|max)                                                      ... run <command>

• result = the command's numeric output (floored to int for score).
• success = 1 if the run command succeeded, else 0 (great for if data/if entity → boolean flag).
• For NBT targets: <type> chooses the stored tag type; <scale> multiplies the value before storing. Because scores are ints, <scale> is how you encode/decode decimals (e.g. store Health ×100 as an int to keep 2 decimals, or write a scaled int back into a float NBT field).

Examples

data/ns/function/store/read_health.mcfunction — read entity NBT → score (with scale for decimals)

# Health is a float; multiply by 100 and floor to keep 2 decimals as an int score
execute store result score @s health_x100 run data get entity @s Health 100
# note: 'data get ... <scale>' already scales+floors, so store captures the scaled int directly

data/ns/function/store/has_diamond.mcfunction — boolean flag from a data test (success)

execute store success score @s hasDiamond run data get entity @s Inventory[{id:"minecraft:diamond"}]
# hasDiamond = 1 if the path exists, else 0

data/ns/function/store/write_health.mcfunction — score → NBT, scaling an int back into a float

# hearts is an int score; write it as a float Health field
execute store result entity @s Health float 0.5 run scoreboard players get @s hearts

data/ns/function/store/count_mobs.mcfunction — count matching entities into a score

execute store result score #global mobCount run execute if entity @e[type=zombie]
# 'if entity' returns the count of matches as its result

Data structures & macro integration

Command storage + data modify ... set value lets you build arbitrary JSON-like trees (maps, lists, nested compounds). Combined with macros (function ... with storage, 1.20.2+) you get data-driven command generation: values pulled from storage are substituted into command text at call time.

Storage as arrays & maps

# a map (compound)
data modify storage ns:db config set value {maxPlayers:8,pvp:1b,motd:"Welcome"}
# a list used as an array/stack/queue
data modify storage ns:db queue set value []
data modify storage ns:db queue append value {id:1,task:"spawn"}   # push back
data modify storage ns:db queue prepend value {id:0,task:"init"}   # push front
data remove storage ns:db queue[0]                                 # pop front
# nested growth
data modify storage ns:db players.Steve.coins set value 100

Macros 1.20.2+

• A macro line starts with $ and may contain $(key) placeholders.
• Call a function passing a compound as arguments:

  function ns:foo with storage ns:db config        # keys of the compound become macro args
  function ns:foo with entity @s SelectedItem       # any block/entity/storage + optional path
  function ns:foo {maxPlayers:8,motd:"Hi"}          # inline compound
  

• Substitution rules: strings insert without quotes; numbers insert as plain text (no type suffix, up to 15 fraction digits); booleans → 1/0; compounds/lists → canonical SNBT.
• Macro keys use only a-z A-Z 0-9 _.

Full example — a data-driven "spawn shop"

data/ns/function/shop/buy.mcfunction — the macro function

$scoreboard players remove @s coins $(price)
$give @s $(item) $(count)
$tellraw @s [{"text":"Bought "},{"text":"$(count)x $(item)","color":"green"},{"text":" for $(price) coins"}]

data/ns/function/shop/load.mcfunction — define the shop as data

data modify storage ns:shop items set value {\
  sword:{item:"minecraft:iron_sword",count:1,price:50},\
  bread:{item:"minecraft:bread",count:16,price:10}\
}

data/ns/function/shop/buy_sword.mcfunction — gate in the caller, then run the macro

# only proceed if the player can afford it, then run the macro with the item's compound
execute if score @s coins matches 50.. run function ns:shop/buy with storage ns:shop items.sword

Here items.sword = {item:...,count:1,price:50}, and each key becomes $(item), $(count), $(price) inside the macro. Adding a new shop item is pure data — no new commands.

Data types, precision & fixed-point math

Scoreboards are 32-bit signed ints only. NBT has byte/short/int/long/float/double. There is no native decimal scoreboard math. All "decimals" on scoreboards are fixed-point: store value × 10^k as an int and remember the implied decimal places.

Precision gotchas

• store result and data get <scale> floor (truncate toward −∞ after scaling). 3.99 → 3. Multiply before storing to keep precision: data get entity @s Health 1000 keeps 3 decimals as an int.
• Int overflow at ±2,147,483,647. Multiplication (*=) overflows silently and wraps. Keep intermediate fixed-point products within range; use a smaller scale factor or split the math.
• Floored division/modulo: /= and %= floor toward −∞, so results for negative operands differ from C-style truncation. -1 %= 4 → 3, not -1. Handle signs explicitly if you need symmetric behavior.
• Float vs double: bare decimals in SNBT are doubles; many entity fields (Health, Motion) are floats/doubles with specific types — writing the wrong type (e.g. an int into a float field) can be rejected or coerced. Match the field's type in store ... entity ... <type>.
• Float rounding: 32-bit floats can't represent every decimal exactly; round-tripping NBT float ↔ scaled int can drift by 1 ulp. For money/counters, keep the authoritative value as a fixed-point int score and treat float NBT as display only.

Fixed-point recipe (2 decimals)

data/ns/function/math/fixed_point.mcfunction

# constants: SCALE = 100
scoreboard players set #100 const 100
# set 3.75  ->  375
scoreboard players set #x math 375
# multiply two fixed-point numbers a*b (both ×100) -> divide by 100 to re-normalize
scoreboard players operation #x math *= #y math      # now ×10000
scoreboard players operation #x math /= #100 const   # back to ×100
# display with 2 decimals via numberformat/macro, or split int/frac:
scoreboard players operation #whole math = #x math
scoreboard players operation #whole math /= #100 const   # integer part
scoreboard players operation #frac math = #x math
scoreboard players operation #frac math %= #100 const    # fractional part (0-99)

Version summary

Sources

• Scoreboard — Minecraft Wiki
• /scoreboard command — Minecraft Wiki
• /trigger command — Minecraft Wiki
• /data command — Minecraft Wiki
• /execute (store) — Minecraft Wiki
• NBT format — Minecraft Wiki
• NBT path format — Minecraft Wiki
• Function (Java Edition) — macros — Minecraft Wiki