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("kore", "game"), "wave")
}

scoreboard players add #wave game_state 1
execute store result storage kore:game wave int 1.0 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.

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("kore", "stats"), "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("kore", "stats"), "charge", DataType.INT)
}

Each of these compiles to an execute store result score ... 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, and the min / max infix operations:

function("self_score_math") {
	val 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.