Leaderboard¶

The leaderboard on the right while you're in a map.

Players¶

int Leaderboard::Players()

How many players have a time on the leaderboard on screen inside a map (Steam's count for that board), or -1 when there isn't one on screen or Steam hasn't answered yet.

Example

int players = Leaderboard::Players();
if (players > 0)
    Log::Info(players + " players on this track");

SetTitleNote¶

void Leaderboard::SetTitleNote(const string &in)

Shows a short note after the leaderboard's title, kept there when the game rebuilds its screens; "" removes it. It goes when the plugin stops. If two plugins set one, the last one shows.

Example

Leaderboard::SetTitleNote("· 12,345 players");

OverallPlayers¶

int Leaderboard::OverallPlayers()

How many players are on the main menu's overall leaderboard (the bar along the top): Steam's entry count for the season board it shows. -1 off the main menu, or before the bar has found its board (a moment after the menu shows). Requires host 0.22.0.

Example

int players = Leaderboard::OverallPlayers();
if (players > 0)
    Leaderboard::SetOverallNote("" + players);

SetOverallNote¶

void Leaderboard::SetOverallNote(const string &in)

Shows a short note before the "overall" label of the main menu's leaderboard bar, kept there when the game rebuilds its screens; "" removes it. It goes when the plugin stops. If two plugins set one, the last one shows. Requires host 0.22.0.

Example

Leaderboard::SetOverallNote("12,583");

SetSource¶

void Leaderboard::SetSource(const string &in trackKey, const string &in title, const array<string>@ names, const array<double>@ times,

Hiscores from your own source for one track, shown by the leaderboard inside the map in place of the game's own list: while the race's Race::TrackKey() is trackKey, the board shows these rows (the game's own row widgets: rank, name, time in seconds) under title, with no world/friends switching. ranks (optional) sets each row's rank (0: its place in the list), so the last row can be the player's own place below the top; highlight marks one row (a lime bar and rank), -1 none; ghosts (optional) sets each row's ghost toggle (on/off), and clicks on rows come through Leaderboard::ExtraRowClicked. With an empty names the board shows the title alone (loading). Call it again whenever the rows change; the last plugin to set a source owns the board. A source applies only on the player's own never-published maps (raced with Tracks::OpenLocal, or test-played in the editor): on an official or workshop track the game's own board and ghosts stay, and the log says why. The same goes for the row ghost, replay and own-best functions below. Requires host 0.26.0.

Example

array<string> names = {"Alice", "Bob", "you"};
array<double> times = {39.912, 40.5, 44.1};
array<int> ranks = {1, 2, 17};
array<bool> ghosts = {true, false, false};
Leaderboard::SetSource(Race::TrackKey(), "online  17 players", names, times, ranks, 2, ghosts);

ClearSource¶

void Leaderboard::ClearSource()

Gives the in-map leaderboard back to the game (your source no longer shows). Requires host 0.26.0.

Example

Leaderboard::ClearSource();

SetRowGhost¶

bool Leaderboard::SetRowGhost(int row, const string &in steamId, const string &in replayJson)

Races a source row's player as the game's own leaderboard ghost: replayJson (the game's ghost JSON, e.g. downloaded from your server) is handed to the game's ghosts for steamId, selected the way the board's own ghost toggle selects one (any ghost selected this way before is hidden), the row lit (ghost toggle on, the game's lime row), and the race restarted the way the restart key restarts it, so the ghost runs from the start with the race clock. The game moves, dresses and name-tags it. On a local map, which has no leaderboard of its own, the host opens the game's ghost session for it. Only while your SetSource applies (on the player's own never-published maps); false (and a warning in the log) otherwise or if the game refused the replay. Requires host 0.26.0.

Example

if (Leaderboard::SetRowGhost(0, "76561198000000000", Net::Body(request)))
    Log::Info("racing the record's ghost");

ClearRowGhost¶

bool Leaderboard::ClearRowGhost()

Hides the ghost SetRowGhost showed and restarts the race, as the board's own toggle turning a ghost off. False if none is shown. Requires host 0.26.0.

Example

Leaderboard::ClearRowGhost();

RowGhost¶

string Leaderboard::RowGhost()

The Steam id whose ghost a source row shows now, or "". Requires host 0.26.0.

Example

if (Leaderboard::RowGhost() != "")
    Log::Info("a ghost is on");

SetOwnReplay¶

bool Leaderboard::SetOwnReplay(const string &in replayJson)

Uses replayJson (the game's ghost JSON, e.g. the player's best downloaded from your server) as the player's own best on the current track while your SetSource applies: the game's PB ghost and the own row's replay come from it instead of the game's local record. Only on the player's own never-published maps, like SetSource. False (and a warning in the log) if it can't be used. Requires host 0.26.0.

Example

if (Leaderboard::SetOwnReplay(Net::Body(request)))
    Log::Info("PB ghost from the online best");

WatchRowReplay¶

bool Leaderboard::WatchRowReplay(int row, const string &in steamId, const string &in replayJson)

Shows a source row's run in the game's replay mode, as the board's own row click does: the replay camera follows that run, the ghost raced now (SetRowGhost) and the player's own best (shown or hidden as in the race) play beside it, the watched row is lit as the game lights a watched row, and the game's own exit from replay mode returns to the race and restarts it. The game's replay camera follows only the ghost session's own ghost (measured), so the host opens the session again with the watched player as its local player for replay mode (and gives the watched ghost's name tag the name in its replay: the game would name it after the local player), and the race's own session again when the game leaves it. Replay mode starts once the game has parsed the replay; the host's replay tools (Replay:: time, seek, camera modes) see it as a replay. Only while your SetSource applies (on the player's own never-published maps); false (and a warning in the log) otherwise. Requires host 0.26.0.

Example

Leaderboard::WatchRowReplay(0, "76561198000000000", Net::Body(request));

ExtraRowGhostClicked¶

int Leaderboard::ExtraRowGhostClicked()

The row whose ghost toggle (the switch at the row's right end) was clicked since you last asked, or -1. A click there isn't also reported by ExtraRowClicked, which is the rest of the row (the tile). Requires host 0.26.0.

Example

int row = Leaderboard::ExtraRowGhostClicked();
if (row >= 0)
    Log::Info("toggle " + row);

SourceShown¶

bool Leaderboard::SourceShown()

Whether the board on screen shows your source now. Requires host 0.26.0.

Example

if (Leaderboard::SourceShown())
    Log::Info("our hiscores are up");

SetExtraRows¶

void Leaderboard::SetExtraRows(const string &in title, const array<string>@ names, const array<double>@ times, const array<bool>@ ghosts,

Rows of your own as a third view of the leaderboard inside a map: a button of the game's own kind, beside its world and friends buttons, switches the board to them (and those two switch it back). They're the game's own leaderboard rows, with a rank, a name and a time (in seconds, shown the way the game shows its own), under title. ghosts sets how each row's ghost toggle looks (on or off) and pinned marks rows with a lime bar and a lime rank. Clicks on a row don't start the game's ghost download: read them with ExtraRowClicked and ExtraRowPinClicked (a click on the rank). An empty names removes the button. If two plugins set rows, the last one shows. Requires host 0.24.0.

Example

array<string> names = {"run 1", "run 2"};
array<double> times = {41.2, 39.8};
array<bool> ghosts = {false, true};
Leaderboard::SetExtraRows("my runs", names, times, ghosts);

SetExtraRowsIcon¶

void Leaderboard::SetExtraRowsIcon(const string &in file)

The image on the extra rows' button: a PNG or JPEG in the plugin's folder (or a full path); "" for the game's own list icon. Requires host 0.24.0.

Example

Leaderboard::SetExtraRowsIcon("runs.png");

ExtraRowsShown¶

bool Leaderboard::ExtraRowsShown()

Whether the leaderboard shows your extra rows now (their button was clicked). Requires host 0.24.0.

Example

if (Leaderboard::ExtraRowsShown())
    Log::Info("showing my rows");

ExtraRowClicked¶

int Leaderboard::ExtraRowClicked()

The extra row clicked since you last asked (not on its rank), or -1. Requires host 0.24.0.

Example

int row = Leaderboard::ExtraRowClicked();
if (row >= 0)
    Log::Info("row " + row + " clicked");

ExtraRowPinClicked¶

int Leaderboard::ExtraRowPinClicked()

The extra row whose rank was clicked since you last asked (a pin), or -1. Requires host 0.24.0.

Example

int row = Leaderboard::ExtraRowPinClicked();
if (row >= 0)
    pinned[row] = !pinned[row];