Leaderboards

The Y8 SDK allows your game to retrieve leaderboard tables and scores, submit player scores, and display leaderboards.

Select your engine below to view the appropriate implementation.

Get Leaderboards

Retrieve the leaderboard tables configured for your application.

JavaScriptUnityConstruct 3Haxe

y8Sdk.getLeaderboards()
    .then((tables) => {
        console.log(tables);
    })
    .catch((error) => {
        console.error(error.message);
    });

To retrieve leaderboards from another game:

y8Sdk.getLeaderboards("otherAppId")
    .then((tables) => {
        console.log(tables);
    })
    .catch((error) => {
        console.error(error.message);
    });

An empty array indicates that no leaderboard tables have been configured.

JsResponse<ScoreTables> response =
    await Y8.Instance.GetLeaderboardsAsync();

if (response.IsSuccess)
{
    Debug.Log(response.Data);
}

If no leaderboard tables have been configured, the returned collection is empty.

GetLeaderboard → On clicked
               → Call getLeaderboards

GetLeaderboard

When the leaderboard data is loaded, the onLeaderboardsLoaded function is triggered.

On function onLeaderboardsLoaded
    → leaderboardData

GetLeaderboard

The leaderboard data is provided as a JSON string.

To retrieve leaderboards from another game:

GetLeaderboard → On clicked
               → Call getLeaderboards

GetLeaderboard

Y8.getLeaderboards(function(leaderboards:Dynamic) {
    if (leaderboards == null) {
        trace("Failed to get leaderboards");
        return;
    }

    trace(haxe.Json.stringify(leaderboards, null, "  "));
});

The callback receives the available leaderboard tables.

If the request fails, the callback receives null.

Get Leaderboard Scores

Retrieve scores from a leaderboard.

JavaScriptUnityConstruct 3Haxe

y8Sdk.getLeaderboardScores({
    table: "level_1",
    page: 1,
    perPage: 10,
    mode: "alltime",
    highest: true,
    playerId: null,
    appId: null
})
.then((scores) => {
    console.log(scores);
})
.catch((error) => {
    console.error(error.message);
});

Parameters

Property	Type	Required	Description
`table`	`string`	Yes	Leaderboard table name.
`page`	`number`	No	Page number. Default: `1`.
`perPage`	`number`	No	Number of results per page. Default: `10`.
`mode`	`string`	No	Time period: `alltime`, `last30days`, `last7days`, `today`, or `newest`.
`highest`	`boolean`	No	Set to `false` when lower scores are better. Default: `true`.
`playerId`	`string`	No	Retrieve scores for a specific player.
`appId`	`string`	No	Retrieve scores from another game.

Result

A page of scores, not a bare array:

{
    page: 1,
    perPage: 10,
    totalPages: 4,
    items: [ /* Score objects */ ]
}

Each entry in items:

Property	Type	Description
`playername`	`string`	Name shown on the board.
`points`	`number`	The score.
`rank`	`number`	Position on the board.
`playerid`	`string`	Player identifier.
`scoreid`	`string`	Identifier for this score entry.
`table`, `tableid`	`string`	The board this score belongs to.
`appid`	`string`	The game it was set in.
`date`, `lastupdated`	`number`	When it was set and last changed.
`rdate`	`string`	The same date, preformatted for display.

An empty items array means the board exists but has no scores yet — not an error.

JsResponse<ScoreTable> response =
    await Y8.Instance.GetLeaderboardScoresAsync(
        "level_1",
        "alltime",
        20,
        1,
        true
    );

if (response.IsSuccess)
{
    Debug.Log(response.Data);
}

Parameters

Parameter	Type	Required	Description
`table`	`string`	Yes	Leaderboard table name.
`mode`	`string`	No	Time period: `alltime`, `last30days`, `last7days`, `today`, or `newest`.
`perPage`	`int`	No	Number of results per page.
`page`	`int`	No	Page number.
`highest`	`bool`	No	Set to `false` when lower scores are better.

GetScores → On clicked
               → Call getScores

GetScores

When the scores data is loaded, the onScoresLoaded function is triggered.

On function onScoresLoaded
    → ScoreData

GetScores

The score data is provided as a JSON string.

Parameters

Parameter	Type	Required	Description
`table`	`string`	Yes	Leaderboard table name.
`page`	`number`	No	Page number. Default: `1`.
`perPage`	`number`	No	Number of results per page. Default: `10`.
`mode`	`string`	No	Time period. Default: `alltime`.
`highest`	`boolean`	No	Set to `false` when lower scores are better.
`playerId`	`string`	No	Retrieve scores for a specific player.
`appId`	`string`	No	Application ID for another game.

Y8.getScores(
    "level_1",
    1,
    10,
    "alltime",
    true,
    function(scores:Dynamic) {
        if (scores == null) {
            trace("Failed to get scores");
            return;
        }

        trace(haxe.Json.stringify(scores, null, "  "));
    }
);

Parameters

Parameter	Type	Required	Description
`table`	`String`	Yes	Leaderboard table name.
`page`	`Int`	No	Page number. Default: `1`.
`perPage`	`Int`	No	Number of results per page. Default: `10`.
`mode`	`String`	No	Time period.
`highest`	`Bool`	No	Set to `false` when lower scores are better.
`callback`	`Dynamic -> Void`	Yes	Called with the leaderboard scores.

Save a Score

Submit a player's score to a leaderboard.

JavaScriptUnityConstruct 3Haxe

y8Sdk.saveLeaderboardScore({
    table: "level_1",
    points: 1500,
    allowDuplicates: false,
    highest: true,
    playerName: null
})
.then(() => {
    console.log("Score submitted");
})
.catch((error) => {
    console.error(error.message);
});

Parameters

Property	Type	Required	Description
`table`	`string`	Yes	Leaderboard table name.
`points`	`number`	Yes	Player score.
`allowDuplicates`	`boolean`	No	Allow multiple scores for the same player. Default: `false`.
`highest`	`boolean`	No	Set to `false` if lower scores are better.
`playerName`	`string`	No	Player name to display. Defaults to the authenticated player's nickname.

int score = 3001;

JsResponse<ScoreSave> response =
    await Y8.Instance.SaveLeaderboardScoreAsync(
        "level_1",
        score,
        false,
        true
    );

if (response.IsSuccess)
{
    Debug.Log("Score submitted");
}

Parameters

Parameter	Type	Required	Description
`table`	`string`	Yes	Leaderboard table name.
`score`	`int`	Yes	Player score.
`allowDuplicates`	`bool`	No	Allow multiple scores for the same player.
`highest`	`bool`	No	Set to `false` if lower scores are better.

SubmitScores → On clicked
               → Call SubmitScores

SubmitScores

Parameters

Parameter	Type	Required	Description
`table`	`string`	Yes	Leaderboard table name.
`score`	`number`	Yes	Player score.
`duplicate`	`boolean`	No	Allow duplicate scores. Default: `false`.
`highest`	`boolean`	No	Set to `false` when lower scores are better.
`playerName`	`string`	No	Player name to display.

Y8.saveScore(
    "level_1",
    1500,
    false,
    true
);

Parameters

Parameter	Type	Required	Description
`table`	`String`	Yes	Leaderboard table name.
`points`	`Int`	Yes	Player score.
`allowDuplicates`	`Bool`	No	Allow multiple scores for the same player. Default: `false`.
`highest`	`Bool`	No	Set to `false` if lower scores are better.

Note

When highest is true, submitting a score lower than the player's existing best does not generate an error. The request succeeds, but the leaderboard remains unchanged.

Display the Leaderboard

Display the built-in leaderboard interface.

JavaScriptUnityConstruct 3Haxe

y8Sdk.showLeaderboard();

You can also specify options:

y8Sdk.showLeaderboard({
    table: "level_1",
    mode: "alltime",
    highest: true,
    useMilli: false
});

The returned Promise resolves when the player closes the leaderboard.

Options

Property	Type	Required	Description
`table`	`string`	No	Leaderboard table to display.
`mode`	`string`	No	Time period to display.
`highest`	`boolean`	No	Whether higher scores rank first.
`useMilli`	`boolean`	No	Display scores as `MM:SS.mmm` time values.

await Y8.Instance.ShowLeaderboardAsync(
    "level_1",
    "alltime",
    true,
    false
);

Debug.Log("Leaderboard closed");

Parameters

Parameter	Type	Required	Description
`table`	`string`	No	Leaderboard table to display.
`mode`	`string`	No	Time period to display.
`highest`	`bool`	No	Whether higher scores rank first.
`useMilli`	`bool`	No	Display scores as `MM:SS.mmm` time values.

ShowLeaderboard → On clicked
               → Call ShowLeaderboard

ShowLeaderboard

Parameters

Parameter	Type	Required	Description
`table`	`string`	No	Leaderboard table to display.
`mode`	`string`	No	Time period to display.
`highest`	`boolean`	No	Whether higher scores rank first.
`useMilli`	`boolean`	No	Display scores as `MM:SS.mmm` time values.

Y8.showLeaderboard(
    "level_1",
    "alltime",
    true
);

Parameters

Parameter	Type	Required	Description
`table`	`String`	Yes	Leaderboard table to display.
`mode`	`String`	No	Time period to display. Default: `alltime`.
`highest`	`Bool`	No	Whether higher scores rank first.

Embed a leaderboard

Instead of the full-screen panel, you can place a leaderboard inside your own interface — a sidebar, a results screen, a menu tab.

JavaScriptUnityConstruct 3Haxe

const leaderboard = y8Sdk.embedLeaderboard({
    target: "#leaderboard-panel",
    table: "level_1",
    mode: "alltime",
    highest: true,
    useMilli: false
});

Remove it when you are done with it:

leaderboard.destroy();

Property	Type	Required	Description
`target`	`string \\| HTMLElement`	Yes	Container element, or a CSS selector for one.
`table`	`string`	No	Leaderboard table to show.
`mode`	`string`	No	Time period.
`highest`	`boolean`	No	Whether higher scores rank first.
`useMilli`	`boolean`	No	Show scores as times rather than numbers.

Give the container a size

The embedded leaderboard fills its container's width and height. If the container has no dimensions of its own it collapses and nothing appears.

Embed after sign-in has been reported

The embed is created immediately, using whichever Y8 site the player came from. Very early in startup that is not yet known, so embedding in your first frame can point the panel at the default site instead of the player's own.

Creating it once authentication has been reported avoids this. The full-screen panel is unaffected — it waits on its own.

Not available on this platform. Use the full-screen leaderboard described above.

Call embedLeaderboard from your event sheet. The target is the HTML element you want it placed into:

embeddedLB = y8Sdk.embedLeaderboard({
    target: "#leaderboard-panel",
    table: "level_1",
    mode: "alltime",
    highest: true
});

Remove it with destroyLeaderboard.

The container needs explicit dimensions, or the panel collapses to nothing.

Not available on this platform. Use the full-screen leaderboard described above.

Best Practices

Retrieve available leaderboard tables before requesting scores.
Verify leaderboard table names before submitting scores.
Submit scores after the relevant gameplay has been completed.
Set highest to false when lower scores represent better results.
Handle asynchronous errors appropriately for your engine.
Use the built-in leaderboard interface for a quick platform experience.
Use the embedded leaderboard when integrating it into your own JavaScript UI.