Scoreboards

Wraps Minecraft scoreboards with two distinct handle types:

• Scoreboard - an objective, identified by name. Create it, display it, name it.
• ScoreboardEntity - one entity's score in one objective. Read it, write it, copy it.

That split mirrors how vanilla splits scoreboard objectives ... from scoreboard players ....

Which handle do I need?

ScoreboardEntity, getScoreEntity, and getScore all require a Function context, so call them inside a function { } block, not at datapack top level.

Objectives

function("scoreboard_setup") {
	scoreboard("kills") {
		create()                             // the objective must exist before any score is written
		setDisplaySlot(DisplaySlots.sidebar) // shows the scores on the right of the screen
		setDisplayName("Kill Count")         // shown to players, unlike the internal name "kills"
	}
}

create() takes an optional criterion, e.g. create(ScoreboardCriteria.DEATH_COUNT).

Per-entity scores

There are two equivalent ways to reach the same ScoreboardEntity - pick whichever reads better at the call site:

function("score_ops") {
	val kills = scoreboard("kills")

	val fromEntity = player.getScoreEntity("kills") // entity-first
	val fromObjective = kills.getScore(player)      // objective-first, same result

	fromEntity.set(10)
	fromEntity.add(5)
	fromEntity.remove(2)
	fromEntity.reset()
}

Operators

ScoreboardEntity supports += and -= against a literal:

function("on_kill") {
	val kills = player.getScoreEntity("kills")
	kills += 1
	kills -= 1
}

The same operators work between two score handles, and *=, /=, %= are available on both sides. Every one of them compiles to a single scoreboard players operation:

function("score_math") {
	val score = player.getScoreEntity("score")
	val kills = player.getScoreEntity("kills")

	score += kills  // scoreboard players operation ... += ...
	score *= kills
	score /= kills  // floored division, as vanilla does
	score %= kills  // floored modulo

	score setTo kills
	score minWith kills   // keeps the smaller of the two
	score maxWith kills   // keeps the larger of the two
	score swapWith kills
}

*=, /= and %= also accept an Int. Vanilla has no literal right-hand side for operation, so Kore reads the value from a fake-player constant, declared once per function in the kore_constants objective (rename it through OopConstants.constantsObjective):

function("halve_score") {
	val score = player.getScoreEntity("score")
	score /= 2
}

scoreboard objectives add kore_constants dummy
scoreboard players set #2 kore_constants 2
scoreboard players operation @e[...] score /= #2 kore_constants

Fake players

A score holder starting with # is a fake player: a holder no real entity owns, which is how datapacks keep globals and constants out of the sidebar. fakePlayer builds an Entity handle for one, so every ScoreboardEntity API works against it:

function("next_wave") {
	val wave = fakePlayer("wave").getScoreEntity("game_state")
	wave += 1
	wave.copyTo(storage("game", "kore"), "wave")
}

scoreboard players add #wave game_state 1
execute store result storage kore:game wave int 1 run scoreboard players get #wave game_state

fakePlayer("wave") and fakePlayer("#wave") both produce #wave. Use the FakePlayer constructor directly for holders that must not carry that prefix, such as the §0..§f holders behind sidebar lines.

A fake player has no entity behind it, so asSelector() throws instead of emitting @e[name=#wave], which matches an entity custom name and would silently target nothing. Only score APIs, which go through asScoreHolder(), accept one.

Expressions

setTo { } computes a score from other scores in one compute, where the scoreboard players operation route needs a temporary holder per step. Inside the lambda, score(entry) reads a ScoreboardEntity and the provider operators build the tree:

function("combo") {
	val kills = player.getScoreEntity("kills")
	val bonus = fakePlayer("bonus").getScoreEntity("game")
	val points = fakePlayer("points").getScoreEntity("game")

	points setTo { score(kills) + score(bonus) * 2 }
}

execute store result score #points game run compute entity @e[...] integer {type:"minecraft:add",inputs:[{type:"minecraft:score",score:kills,target:{type:"minecraft:context",target:target_entity}},{type:"minecraft:mul",inputs:[{type:"minecraft:score",score:game,target:{type:"minecraft:fixed",name:"#bonus"}},2]}]}

A fake player is read by name. A real entity is read as the compute entity target, so an expression reads one real entity at most, in as many objectives as it needs, next to any number of fake players. Reading two different real entities isn't possible because compute has one target: copy one score into a fake player first. A selector that can match several entities throws for the same reason. With only fake players, the command is compute default. data(storage).computeScores("path") { ... } builds the same expression into a data modify target, with the same rules.

A lambda returning a float provider runs in float mode, and the optional scale multiplies the result before it is rounded down into the score (2.5 with a scale of 100 gives 250). That makes random floats a one-liner:

function("roll") {
	val chance = fakePlayer("chance").getScoreEntity("game")
	chance.setTo(1000f) { uniform(0.5f, 2f) }  // a score between 500 and 1999
}

execute store result score #chance game run compute default float {type:"minecraft:uniform",max:2,min:0.5d} 1000

A Float factor on *= and /= is one compute too, where an Int factor keeps the scoreboard players operation route above:

function("bonus") {
	val gold = fakePlayer("gold").getScoreEntity("game")
	gold *= 1.5f
	gold /= 2.5f
}

execute store result score #gold game run compute default float {type:"minecraft:mul",inputs:[{type:"minecraft:from_int",input:{type:"minecraft:score",score:game,target:{type:"minecraft:fixed",name:"#gold"}}},1.5d]}
execute store result score #gold game run compute default float {type:"minecraft:div",left:{type:"minecraft:from_int",input:{type:"minecraft:score",score:game,target:{type:"minecraft:fixed",name:"#gold"}}},right:2.5d}

Copying between scores, NBT, and counts

function("sync") {
	val stat = player.getScoreEntity("stats.charge")

	stat.copyFrom(player.asSelector(), "deaths") // from another score

	// from NBT: scores are integers, so a scale converts fractional values
	stat.copyDataFrom(player, "Inventory[0].count")
	stat.copyDataFrom(storage("stats", "kore"), "charge")

	// from a live count of matching entities
	stat.copyEntityCountFrom(entity(EntityTypes.ZOMBIE, limitToOne = false))
	stat.copyMemberCountFrom(team("red"))

	// and back out into NBT
	stat.copyTo(player, "kore.charge", DataType.INT)
	stat.copyTo(storage("stats", "kore"), "charge", DataType.INT)
}

A score to score copy is a single scoreboard players operation <this> = <source>, the NBT and count copies compile to an execute store result ... run ... chain, so you never have to write the store plumbing by hand.

Raw selectors and @s

ScoreboardEntity is built around an OOP Entity handle, and Entity always renders as @e[...]. There is no Entity that renders as @s, and self() returns a SelectorArgument, not an Entity - so it cannot be passed to getScoreEntity or getScore.

For @s (or any other raw selector) use the core scoreboard.objective(...) DSL instead. It returns a PlayerObjective, which supports the same arithmetic including operators:

function("charge_up") {
	val lastCharge = scoreboard.objective(self(), "last_crystal_charge")
	lastCharge += 10
}

This emits scoreboard players add @s last_crystal_charge 10.

PlayerObjective covers set, add, remove, reset, get, enable, operation, the += / -= / ++ / -- operators (++ / -- need a var, Kotlin reassigns the variable), and the min / max infix operations:

function("self_score_math") {
	var mine = scoreboard.objective(self(), "score")
	val best = scoreboard.objective(literal("#best"), "score")

	mine++
	best max mine // keeps the larger of the two in best
	mine.operation(Operation.SET, literal("#best"), "score")
}

Use scoreboard.objective(...) whenever the score holder is @s or any selector you already have as an Argument. Use ScoreboardEntity when you hold an OOP Entity, including a fake player.

Practical pattern

function("match_setup") {
	val kills = scoreboard("kills")
	kills.create()
	kills.setDisplaySlot(DisplaySlots.sidebar)

	val playerKills = kills.getScore(player)
	playerKills.set(0)
}

Configure the objective once, then retrieve score handles wherever gameplay code needs to increment, reset, or copy values.

See also

• Entities & Players - The Entity handles that getScoreEntity and getScore need.
• Teams - scoreboard.getScore(team) and team member counters.
• Timers - Scoreboard-backed countdowns built on this API.