Free open source global leaderboard

[Inpultion (Nash)]

Heyo, before I explain my module and the mechanics of it, I’d like to mention that this is my first resource/contribution on here. If you have any criticism feel free to throw it all at me. Any criticism on how I could structure/compose my next resource/contribution would also be greatly appreciated! Thanks

Quick disclaimer to some

If you’re unfamiliar with programming, I suggest looking at a youtube tutorial instead of this post. Why? Well I think it’d be a little daunting to comprehend the module in its entirety. However, if you insist on using this module, feel free to ask for help below if you’re stumped

Leaderboard API:

• .new(contentData: leaderboardData) – Constructs a new leaderboard class.
• :DisableLocalTesting() – Stops “test accounts” saving to the leaderboard. Useful for when you’re running a local server and don’t want “test accounts” to append to the leaderboard.
• :Clear() – Clears all the icon templates in the leaderboard icon parent.
• :Load() – Creates brand new icon templates which are displayed on the leaderboard icon parent.
• :Update() – Exactly the same as doing :Clear() return :Load().
• :Append(userId: number, value: number) – Appends a value to the leaderboard given a userId and value. Equivalent to a Set method.
• :Erase(userId: number) – Removes a value from the leaderboard given a userId. Just a reminder, this method shouldn’t be used too often. Equivalent to a Remove method.
• :ClearCache() – Clears the cache if you’re using one.
• :AutoUpdate(updateTime: number) – Creates a loop to “auto update” the leaderboard every x seconds. Equivalent to using :Update() in a while loop.
• :BreakAutoUpdater() – Stops the auto updater.
• :AttachRefreshTimer(refreshTimer: TextLabel) – If you have a TextLabel which should display the time until the next “refresh”, just pop it into the function and you’re good

Okay, the API is out of the way. Now, what is this “contentData” in the constructor function?
The “contentData” is a table which contains data that the leaderboard uses to operate properly.

Here’s a list of all the content data:

• datastoreKey – The datastore key used for saving, loading and updating the leaderboard. This is a string type and the leaderboard will throw an error if it’s not.
• leaderboardIconParent – The parent for any created icon templates. This has to be an Instance type.
• iconTemplate – The module associated to creating the actual icon template. The base icon template can be found in a module within the main module.
• format – How the value is altered. There are three built-in formats: “Comma”, “Abbreviate” and “Time”. You can also pass a function if you want to have your own formatting function.
• lines – This is the max amount of icon templates that can appear on the leaderboard.
• descendingOrder – Whether or not the icon templates appear in ascending or descending order.
• displayNamesEnabled – Should “DisplayNames” be shown in the icon template.
• showDisplayNameIfSameAsName – If a player’s “Name” and “DisplayName” are the same, should the “DisplayName” still be displayed. e.g. Inpultion(@Inpultion)
• thumbnailsEnabled – Whether or not player icons will be displayed.
• thumbnailCache – Whether or not to save player icons into a cache, so that the next time the leaderboard refreshes, it can be collected from a cache instead of being acquired again.
• userDataCache – Whether or not to save player data into a cache, so that the next time the leaderboard needs to request a “DisplayName” and or “Name” it will acquire it from the cache instead.
• debug – Whether or not warnings are displayed or not. Enabling this feature may help with seeing if the roblox datastores are experiencing issues.

Default contentData:

• datastoreKey – No default value set. This is a required field to fill.
• leaderboardIconParent – No default value set. This is a required field to fill.
• iconTemplate – Default icon template constructor function.
• format – “Comma”.
• lines – 25.
• descendingOrder – false.
• displayNamesEnabled – true.
• showDisplayNameIfSameAsName – false.
• thumbnailsEnabled – false.
• thumbnailCache – true.
• userDataCache – true.
• debug – false.

Right, time to elaborate on a couple of things.

1. If you’re looking to create a custom icon template, make sure that you pass the “iconTemplate” as a function, as such:

-- modules
local leaderboardModule = require(14717967724)

-- functions
local newLeaderboard = leaderboardModule.new({
	iconTemplate = function(name, value, rank, displayName, thumbnail, showDisplayNameIfSameAsName)
	   local iconTemplateFrame = Instance.new("Frame")
	
       -- blah, blah, blah. Create the icon stuff here.

	   return iconTemplateFrame
    end
})

Make sure that the function also holds those same arguments; in that order, or things may not work as you intend them to. Make sure to return the icon template “container”, otherwise the leaderboard won’t parent the icon template to the leaderboard.

2. When creating a custom formatter. Make sure that you pass “format” as a function, as such:

local newLeaderboard = leaderboardModule.new({
	format = function(value: number)
        return value -- Or whatever you change the value to.
    end,
})

Keep in mind that if the format function doesn’t return a number, it may pose an error, breaking the leaderboard.

Where can I get the module? Right here. You can alternatively do require(14717967724) as a shortcut.

( For now there isn’t a github sowry )

I’d also like to thank @okeanskiy for one of the built-in formatters ( The number abbreviator ) You can check out his video on number abbreviating!

Abbreviate Numbers/Currency! - Roblox (Rounding and Formatting Strings)

Is credit required? Not at all. Credit would be nice, but again, it’s not something I’ll run after you for… (
or so you think >:) )

p.s, Here’s a quick video showing a basic leaderboard template in action. (As well as an uncopylocked place)

Place.

If you have any questions, critiques or suggestions which may pose benefit to this resource, feel free to let me know below.

Tell me what you think about the module:

• Great module, no issues.
• It’s okay.
• Pointless module.

[toto1230kl (Jax)]

this was the best open source leaderboard I have ever seen! this will definitely help a lot of developers

[toto1230kl (Jax)]

Doesn’t support multiple leaderboards? I went to put another leaderboard and it didn’t work…

[Inpultion (Nash)]

Version 1.0.1:

• Fixed multiple leaderboards not displaying correctly ( I should’ve originally tested multiple leaderboards, my bad! ) Though remember to change the datastoreKey.
• Added a new method :BindRankToCharacter(rank: number, character: Model). With this method, you’re able to bind a “rank” to a “character”. Used if you want to display the player’s character who “holds” that rank.

How do I acquire the new version? If you’re using the require method: require(14717967724), you don’t need to do anything, you’re already up to date! However, if you imported the module via the toolbox, simply reimport the module and you’re good to go.

p.s: I updated the place file if you want to see how the new methods work

[CelestialHonour (Celestial)]

Great work! I have checked it out and its one of the best ones I have used so far, even though its the very first version. I would like to suggest a change I made, I added additional "statName:string " in the contentData.
and made changes as follows:

self.StatName = contentData.statName..": " or " "--mainmodule.new function

and then:

self.template( --mainModule:Load() function
			(userDataCache[userId] or flippedUserData[userId] or self.fakeUserData).Username,
			value,
			rank,
			(userDataCache[userId] or flippedUserData[userId] or self.fakeUserData).DisplayName,
			thumbnail,
			self.showDisplayNameIfSameAsName,
			self.StatName
		).Parent = self.iconParent

finally, in the icontemplate:

valueLabel.Text = statName..tostring(value)

I also set the offset to -30 as it seemed better and not too far away from the display name.

valueLabel.Position = UDim2.new(1, -30, 0.5, 0)

Outcome:

^^ here I set the “statName” to “Level”. You know, I thought it was a great addon, well its optional to use so doesn’t make much difference does it?

Thank you for this great module. >:)

[Inpultion (Nash)]

Version 1.0.2:

• Added two new variables in the contentData table. frontPrefix allows you to set a, well, front prefix to your finalized text value e.g. “Coins: 100,000”. backPrefix allows you to se a back prefix e.g. “100,000 coins”. You can use them both in parallel to create some neat text: “Coins: 200k”, “>100<”, “—>100k<—” or anything that you desire ( Thank you so much @CelestialHonour for the neat idea )
• Added a “minor changes” section in the VERSION module within the actual leaderboard module for side information which may not be documentated in these “version” replies.

The prefixes are listed as such in the contentData:

local leaderboard = leaderboardModule.new({
	frontPrefix = "<", -- Change this to anything you like.
	backPrefix = ">", -- You can also leave them out if you don't want any prefix text.
})

Here’s another example:

local leaderboard = leaderboardModule.new({
	frontPrefix = "Coins: ",
})

Thanks to anyone whom uses this module!
Have a lovely day.

p.s. I updated the place if anyone would like to check out the prefix stuff.

[toto1230kl (Jax)]

Suggestion: BindRankToCharacter(rank, character, ID), the ID would be from an animation to make the character animate

[Inpultion (Nash)]

Most games do indeed have the characters do some sort of animation(s). Though I think this suggestion branches more toward the character customizability rather than the actual leaderboard module itself. However, I’ll find a suitable workaround to implement a similar, more robust feature soon, thanks!

[jelloman]

@Inpultion

14717967724

The link to Module is broken in the post. Has the module been taken down?

[iiNeZoXii (Mvke)]

He got banned permanently from roblox actually.

[iiNeZoXii (Mvke)]

Here his fully module if you need it

Creator Hub - Store

[jelloman]

Thanks so much for sharing this! From looking at the code, this will work great!

[agKing_21]

Amazing work module is very simple to use and very optimized and efficient this is a game changer for Global Leaderboard