GS - Stats
A Godot asset for reporting stats and more. This belongs to TMC's ecosystem of Godot open source assets.
Per-player statistics a game declares once and reports in batches. Counters, gauges, bests and lowests are merged by a rule the game states, and filed to the TMC back end without a server ever handing over an account id.
State the merge rule once per stat (add, replace or keep the better) and every party applies it the same way: the server counting, the reporter batching and the site storing.
Install
- Get Godot 4.7.
- Either use dot-bootstrap, which clones every project and links the addons, or copy
addons/dot_stats/and dot-core'saddons/dot_core/into your project and enable dot-stats in Project > Project Settings > Plugins.
dot-core is the only dependency. dot-auth is optional and supplies the two clients (DotBackboneClient for a server, DotAuthClient for a player).
Use
var schema := DotStatsSchema.new()
schema.define(&"kills").publish = true
schema.define(&"top_speed", DotStatsDef.Kind.BEST, "Top speed").publish = true
schema.define(&"level", DotStatsDef.Kind.GAUGE) # kept, never reported
var tracker := DotStatsTracker.new()
tracker.schema = schema
tracker.report_to_backbone = true
tracker.reporter.client = backbone # dot-auth's DotBackboneClient
add_child(tracker)
tracker.begin(player_key, display_name) # the scoped key, never the account id
tracker.record(player_key, &"kills")
tracker.record(player_key, &"top_speed", 41.2)
tracker.end(player_key) # reports the last delta, forgets them
Every report_interval seconds (default 30) and once more on shutdown, the tracker sends each player's delta since the last report, such as {"kills": 3, "top_speed": 41.2}. The site merges each by its kind.
Lifetime totals on the server
var store := DotStatsStoreSql.new(driver) # any dot-sql driver; or DotStatsStoreMemory
await store.open() # creates or migrates its table
tracker.store = store # before add_child
Each reported delta is also merged into the store by the same rule, so a server with no back end still keeps every player's totals. The store answers values_for(player), top(stat, limit, offset) (a LOWEST ascending, the rest descending, ties sharing a rank), rank_of(stat, player) and remove_player(player).
DotStatsStoreSql speaks SQLite, PostgreSQL and MySQL/MariaDB through dot-sql, without needing it to parse. Writes are guarded by a revision, so two servers sharing a table add up instead of overwriting. A failed write is kept for the next flush and never counts a counter twice.
Player-reported stats
A player's own client can report its own figures with the player's token and no integration credential:
var mine := DotStatsClient.new()
mine.schema = schema
mine.client = auth_client # dot-auth's DotAuthClient
add_child(mine)
mine.record(&"launches")
var held := await mine.fetch_mine()
Both land on the same rows. Keep anything competitive on the server; this is for a diary.
Stat catalogue file
tools/export_site_defs.gd writes a game's published stats as the site's dot-stat-defs JSON, from the schema the game really builds, so the site owner imports it instead of retyping it. Run it from the game project with Godot headless as a script, passing --source (a script path), --method (the function returning the DotStatsSchema) and --out.
| Option | Does |
|---|---|
--check |
Writes nothing and exits 1 when the file on disk is stale. |
--game <id> |
Pins the site app id. Left out by default so one file imports anywhere. |
The file is DotStatsSchema.to_site_defs(). A scaled difference is skipped with a warning, because the site's diff ignores scale.
Testing
Import the project once, then run examples/stats_selftest.tscn headless with Godot. examples/stats_sql_live.tscn runs the SQL store against real databases through ../dot-sql/tools/test_live.sh. More in docs/.
Status and licence
Part of the Gamespice platform: a family of Godot addons. Written with Claude Code and maintained by gamemann. Every addon has headless tests, but little of this has been played by real users yet, so expect rough edges and please open an issue when you hit one.
MIT licence, see LICENSE. The only closed part of the Gamespice platform is the web back end; you can use your own instead of Gamespice's.
Engagement Over Time
GS - Stats is a Godot asset. It has 1 download, 26 views, and 0 favorites. This item belongs to 1 collection and 3 tags.
Reviews
Log in to leave a review.
Comments (0)
Log in to comment.
