GS - Leaderboard
A Godot asset for sending data like leaderboards and more. This belongs to TMC's ecosystem of Godot open source assets.
Leaderboards and player statistics for any Godot game, plus the path from a game server to the TMC website's leaderboards.
Part of the Gamespice collection: modular, MIT-licensed building blocks for games on the Gamespice platform (only the TMC website back end is closed). It was built with Claude Code and its headless suite passes, but little of it has met real players yet, so expect rough edges and please report what you find.
What you get
A board orders one number per player within a scope you choose, such as map, track and style. "Fastest time on surf_beginner", "most kills this week" and "highest score" are one thing with different settings.
- Boards with four orderings (
TIME,SCORE,POINTS,PENALTY) and display that knows a time from a score. - Ranks. Ties share a rank (1, 2, 2, 4) in every store.
- Player statistics: counters, bests and lowests, and any counter can become a board.
- Stores: in memory, or
DotLeaderboardStoreSqlfor SQLite, Postgres and MySQL/MariaDB through dot-sql. - A reporter that batches submissions to the TMC backbone and keeps its queue through an outage.
Install
Copy addons/dot_leaderboard/ and dot-core's addons/dot_core/ into your project and enable dot-leaderboard in Project > Project Settings > Plugins. dot-auth, dot-timer, dot-server and dot-sql are optional and never named in the source.
Use
var boards := DotLeaderboardManager.new()
boards.store = DotLeaderboardStoreMemory.new()
add_child(boards)
var fastest := DotLeaderboardDef.make(&"fastest", DotLeaderboardDef.Kind.TIME)
fastest.display_name = "Fastest time"
fastest.publish = true # opt in to the site leaderboard
boards.define(fastest)
# one definition, one board per (map, track, style)
await boards.submit(
&"fastest",
{"map": "surf_beginner", "track": "0", "style": "normal"},
player_id, player_name, run.time()
)
var page := await boards.page(&"fastest", {"map": "surf_beginner", "track": "0", "style": "normal"})
for entry in page.value:
print("%d. %s %s" % [entry.rank, entry.player_name, fastest.format_value(entry.value)])
Statistics
var session := DotStatSet.new()
session.add(&"jumps", stats.jumps)
session.set_best(&"top_speed", stats.max_speed)
await boards.add_stats(player_id, session)
# any counter can become a board
await boards.publish_stat(&"most_jumps", {}, player_id, player_name, &"jumps")
A database
var store := DotLeaderboardStoreSql.new(driver) # any dot-sql driver
await store.open() # creates or migrates its two tables
boards.store = store
await boards.submit_async(&"fastest", scope, player_id, player_name, run.time())
var page := await boards.page_async(&"fastest", scope)
Use the _async forms (submit_async, page_async, entry_for_async) with a database store. The plain forms refuse a store that has to wait. add_stats, stats_for and publish_stat are always awaited. Table names are the entries_table and stats_table settings (defaults dot_leaderboard_entries and dot_leaderboard_stats). Counters are added inside the database, so two servers sharing it do not lose each other's updates.
Reporting to the website
boards.report_to_backbone = true
boards.reporter.client = backbone_client # dot-auth's DotBackboneClient
This needs the LEADERBOARD_WRITE scope on a server or app integration. Entries are queued and sent in batches, and the queue survives an outage.
Board definitions file
tools/export_site_defs.gd writes your boards as the website's dot-leaderboard-defs JSON, for the dashboard import or a deploy. Run it from the game project.
| Option | Meaning |
|---|---|
--source |
Script with the static method that returns an array of DotLeaderboardDef. |
--method |
The method name. |
--out |
Output file (default deployment/leaderboard-defs.json). |
--game |
Pin the site app id (unset by default). |
--check |
Exit 1 if the file is stale. |
A board is identified by key plus scope. Importing merges, and boards the file does not mention are kept with their entries.
More
docs/ explains the design choices.
Test
godot --headless --path . --import
godot --headless --path . res://examples/leaderboard_selftest.tscn
# the SQL store against real SQLite, Postgres and MariaDB (dot-sql linked in addons/)
../dot-sql/tools/test_live.sh . res://examples/leaderboard_sql_live.tscn
Licence
MIT. See LICENSE.
Engagement Over Time
GS - Leaderboard is a Godot asset. It has 1 download, 27 views, and 0 favorites. This item belongs to 1 collection and 2 tags.
Reviews
Log in to leave a review.
Comments (0)
Log in to comment.
