Scoreboards

A scoreboard holds named objectives, and each objective holds a score per entry - a player, an entity, or any plain string you choose. Display an objective in a slot and the client draws it: a sidebar on the right, a number under every player's name tag, or a column in the pause-screen player list.

Display an objective

The server keeps one primary scoreboard at getServer().getScoreboard(). Add an objective to it, drop the objective into a slot, and set scores - here a "blocks mined" tally in the sidebar that climbs as players dig:

#include <endstone/endstone.hpp>

namespace es = endstone;

class MyPlugin : public es::Plugin {
public:
    void onEnable() override
    {
        objective_ = getServer().getScoreboard()->addObjective(
            "mined", es::Criteria::Type::Dummy, "Blocks Mined");
        objective_->setDisplay(es::DisplaySlot::SideBar, es::ObjectiveSortOrder::Descending);
        registerEvent(&MyPlugin::onBlockBreak, *this);
    }

    void onBlockBreak(es::BlockBreakEvent &event)
    {
        auto score = objective_->getScore(&event.getPlayer());
        score->setValue(score->getValue() + 1);
    }

    void onDisable() override
    {
        objective_->unregister();
    }

private:
    std::unique_ptr<es::Objective> objective_;
};

The pieces:

• Criteria::Type::Dummy means the server never touches the score - your plugin owns it. It's the criteria you want for anything you drive yourself.
• getScore(entry) returns a std::unique_ptr<Score> whose value you read with getValue and write with setValue. The entry is a ScoreEntry - a Player *, an Actor *, or a std::string.
• setDisplay puts the objective in a slot - SideBar, BelowName, or PlayerList - with a sort order. unregister() removes the objective entirely; do it in onDisable so a reload starts clean.

If you've used the in-game /scoreboard command, the API maps onto it one-to-one - each call above is the programmatic form of a command you could type:

Players, entities, and text rows

An entry is whatever a score hangs off. getScore accepts three kinds, and the type you pass decides what gets tracked:

objective_->getScore(&player)->setValue(10);          // a real player, by identity
objective_->getScore(&zombie)->setValue(3);           // any Actor (mob, entity)
objective_->getScore("Server Total")->setValue(999);  // plain text - a free-standing label row

• A Player * is tracked by the player's identity, so the score follows them across reconnects and renames, and shows under their name tag in the BelowName slot.
• An Actor * works the same way for entities - useful for per-mob counters.
• A std::string is just text: a standalone named row tied to nobody. These are how you draw arbitrary text lines, like the "Coins" and "Level" rows in the next section.

A different scoreboard for each player

This is where Endstone goes beyond what you can do from add-ons. The vanilla script API scoreboard and the /scoreboard command share one world scoreboard - every player necessarily sees the same objective and the same values. Endstone instead lets you build a scoreboard per player and assign it individually:

auto board = getServer().createScoreboard();  // a fresh, independent scoreboard
auto objective = board->addObjective("hud", es::Criteria::Type::Dummy, "Your Stats");
objective->setDisplay(es::DisplaySlot::SideBar, es::ObjectiveSortOrder::Ascending);

objective->getScore("Coins")->setValue(coins);  // plain strings make label rows
objective->getScore("Level")->setValue(level);

player.setScoreboard(*board);                   // only this player sees it

createScoreboard() hands back a standalone std::shared_ptr<Scoreboard>, and setScoreboard swaps which one that single player renders - so two players can be looking at completely different sidebars at the same moment. Because score entries can be arbitrary strings, each row is really a line of text you control, and the number on the right is just another field to drive.

To send a player back to the shared view, assign the primary scoreboard again:

player.setScoreboard(*getServer().getScoreboard());