Unity SDK · Add Leaderboard to Scene

A one-click scaffolder that drops a working, styled leaderboard widget into the active scene - uGUI or UIToolkit, your choice.

Prerequisites

KalmForge SDK installed in your Unity project.
API key configured in Window → KalmForge.
An open scene to drop the widget into.
UIToolkit variant requires the UI Toolkit package (ships with Unity 2021.2+).

What it is

Open from KalmForge → Add Leaderboard to Scene (also in GameObject → KalmForge → Leaderboard Widget). The wizard places a fully wired, working leaderboard prefab into the active scene in one click.

Wizard options

Scaffolder configuration

Name	Type	Description
Leaderboard key	string	Pre-populated from the Leaderboard Setup Wizard if you've run it.
UI system	uGUI \| UIToolkit	Pick the rendering stack that matches your project.
Visual style	Styled \| Bare	Styled = KalmForge dark theme. Bare = unstyled structure only.
Output folder	AssetPath	Where generated prefabs / UXML / USS are written.
Wrap in new Canvas	bool	(uGUI only) Optionally create a fresh Canvas for the widget.

Preview panel

A live UIElements mockup inside the wizard shows exactly what the chosen variant will look like - with sample data - before you place anything in the scene.

[SCREENSHOT: Scaffolder wizard - preview panel]

uGUI variant

The uGUI scaffolder writes:

LeaderboardWidget_uGUI_Styled.prefab or LeaderboardWidget_uGUI_Bare.prefab
Row sub-prefabs: LeaderboardRow.prefab, LeaderboardPlayerRow.prefab

Uses the LeaderboardWidget MonoBehaviour. A Canvas is detected or created automatically.

UIToolkit variant

Generates a UXML + USS file pair plus a prefab containing a UIDocument wired to LeaderboardUIToolkitController. No Canvas required.

Prefab contents

Scrollable entry list
Header with board name and subtitle (player count, next rotation date)
Column headers (Rank, Player, Score)
Refresh button and status label
Current player row highlighted in the accent colour

Widget API

Both LeaderboardWidget (uGUI) and LeaderboardUIToolkitController (UIToolkit) expose the same public API:

LeaderboardWidget / LeaderboardUIToolkitController

Name	Type	Description
FetchAsync()	Task	Manually trigger a fetch and UI refresh.
SubmitScoreAsync(double score, string playerName)	Task	Submit a score then refresh the list.
OnEntriesLoaded	event	Fires when entries are loaded.
OnFetchError	event	Fires on a fetch failure.

exampleC#

1var widget = FindObjectOfType<LeaderboardWidget>();
2widget.OnEntriesLoaded += entries => Debug.Log($"Loaded {entries.Count} rows");
3widget.OnFetchError    += err     => Debug.LogWarning(err);
4
5await widget.SubmitScoreAsync(12_500, "Cipher");

Row naming convention

The widget finds child GameObjects named Rank, Name and Score (case-insensitive) anywhere in the row hierarchy. Rearrange the prefab structure freely as long as those names stay.

Note

The current player's row is highlighted automatically using KalmForgeIdentity.PlayerId.

Styled variant colours

Styled palette (for reference)

Name	Type	Description
Background	#1C1F24	Widget surface.
Header	#2B2E35	Header band and column headers.
Accent	#47C79E	Refresh button, focus ring.
Player highlight	rgba(71,199,158,0.12)	Current player row tint.

Next steps

Wire submission from gameplay using the Leaderboards runtime API.
Run the Leaderboard Setup Wizard to generate a typed bootstrap helper.