SimpleLeaderboard

Global leaderboards - minimal setup required, but fully customizable if needed.

Usage

local SimpleLeaderboard = require(ServerScriptService.ServerPackages.SimpleLeaderboard)

SimpleLeaderboard.new({
	Name = "Cash",
	GetStat = function(player)
		return MyDataLayer.Get(player, "Cash")
	end,
	Renderer = SimpleLeaderboard.BoardRenderer.new({
		Container = leaderboardGui.Frame.ScrollingFrame,
		Template = ReplicatedStorage.Templates.LeaderboardEntry,
	}),
})

The board starts automatically, saving online players' Cash every SaveInterval seconds and refreshing the UI every UpdateInterval seconds.

SimpleLeaderboard.new(config: BoardConfig): Board

Methods

• Board:Start() - begins the save loop and the UI update loop. Boards start automatically by default.
• Board:Stop() - halts both loops; safe to Start() again later.
• Board:Destroy() - stops and permanently disables the board.

SimpleLeaderboard.BoardRenderer.new(config: RendererConfig): Renderer

Builds a default renderer for a ScrollingFrame of cloned template entries.

SimpleLeaderboard.BoardRenderer.Multi(config: MultiRendererConfig): Renderer

Like BoardRenderer.new, but renders the same entries into several containers - for a leaderboard shown on more than one board in the world. Every container gets its own rows, cloned from the same Template.

SimpleLeaderboard.new({
	Name = "Cash",
	GetStat = getCash,
	Renderer = SimpleLeaderboard.BoardRenderer.Multi({
		Containers = {
			workspace.Lobby.CashBoard.SurfaceGui.ScrollingFrame,
			workspace.Shop.CashBoard.SurfaceGui.ScrollingFrame,
		},
		Template = ReplicatedStorage.Templates.LeaderboardEntry,
	}),
})

Defaults

• BoardRenderer.SetDefaultTemplate(template: GuiObject) - sets a fallback Template so it doesn't need to be passed to every RendererConfig.
• BoardRenderer.SetDefaultGuiFormatter(formatter: GuiFormatter) - same, for GuiFormatter.
• BoardRenderer.DefaultGuiFormatter - the built-in formatter, so a custom one can call it and then adjust.

SimpleLeaderboard.Serialize

Pairs of (Serializer, Deserializer) for stats that don't fit directly into an OrderedDataStore's integer storage:

• Serialize.Log(precision: number?) - stores via log10, for stats that can exceed 2^63 (e.g. cash). Lossy past precision digits.
• Serialize.Negatives(bias: number?) - shifts negative-capable stats into non-negative range.
• Serialize.Divide(factor: number?) - divides by a fixed factor, for stats with more precision than integer storage allows (e.g. thousandths).

SimpleLeaderboard.StatSource

A helper for data layers that store multiple stats under one general accessor (e.g. ProfileStore-style profile.Data[key]). Wrap it once and get a GetStat function per key, instead of writing a closure for every board.

local stats = SimpleLeaderboard.StatSource.new(function(player, key)
	local profile = ProfileStore:GetProfile(player)
	return profile and profile.Data[key]
end)

SimpleLeaderboard.new({
	Name = "Cash",
	GetStat = stats:GetStat("Cash"),
	...
})

SimpleLeaderboard.new({
	Name = "Rebirths",
	GetStat = stats:GetStat("Rebirths"),
	...
})

• StatSource.new(source: (Player, key: string) -> number?): StatSource
• StatSource:GetStat(key: string): StatGetter - returns a (Player) -> number? bound to key, for use as a BoardConfig.GetStat.