Dot - Achievements

This is the achievements asset for TMC's Dot collection. What a player has earned, as a document a dedicated server can check without ever loading a picture.

This collection of assets provides modular building blocks for creating games and applications within the TMC ecosystem, ensuring consistency and interoperability across all dot-* assets. This includes core functionality, networking, authentication, cloud integration, and more.

These assets are COMPLETELY OPEN SOURCE. You are free to use, modify, and distribute them under the terms of the MIT license. The only thing not open source is the back-end web infrastructure. So if you opt into using your own authentication backend instead of integrating with TMC, you will need to build and integrate your own back-end infrastructure.

From Maintainer & WARNING

This asset, along with all the others, was built initially with Claude Code and will continue to be maintained and extended using it. This is because I (gamemann) cannot build the entire TMC platform alone (I wish I could lol).

Please treat this as partially tested. Every asset has its own headless test suite and those suites pass, but very little of this has been in front of real players yet. Expect rough edges, and please report anything you run into.

I intend on reviewing code, testing, and editing documentation regularly. If you're interested in helping out, please let me know!

Achievements

Rules over per-player numbers, declared once. Counters, bests, tiers, hidden and secret entries, progress bars that do not lie, a pluggable store, and a batched reporter for the TMC backbone.

Why

An achievement whose condition lives inside the code that awards it is one nobody can list, show progress towards, or check a save file against. Stating it as data instead means a server can validate the whole catalogue at boot, decide what somebody has earned, and report it, without loading a mesh, an icon or a scene. That is the same reason dot-loadout and dot-user-avatar are documents rather than objects.

Installing

Copy addons/dot_achievements/ and dot-core's addons/dot_core/ into your project and enable dot-achievements in Project → Project Settings → Plugins.

dot-stats is optional and is the natural source of the numbers; DotAchievementStatsLink bridges to it without naming it. dot-auth supplies the backbone client and is likewise not named anywhere in the source. Requires Godot 4.7 or newer.

Five minutes

var catalogue := DotAchievementCatalogue.of([
    DotAchievement.counter(&"k10",  "First Blood", &"kills", 10),
    DotAchievement.counter(&"k100", "Centurion",   &"kills", 100),
    DotAchievement.make(&"flawless", "Flawless", [
        DotAchievementRule.make(&"round_wins", 1),
        DotAchievementRule.make(&"deaths", 0, DotAchievementRule.Op.AT_MOST),
    ]),
])

var tracker := DotAchievementTracker.new()
tracker.catalogue = catalogue
tracker.store = DotAchievementStoreFile.new("user://achievements")
tracker.unlocked.connect(func(player: String, a: DotAchievement) -> void:
    hud.toast("%s unlocked" % a.display_name))
add_child(tracker)

await tracker.begin(player_key)         # loads their lifetime numbers
tracker.record(player_key, &"kills", 1)
await tracker.end(player_key)           # saves

record() merges by the kind the rule declared, so a counter adds and a best keeps the better. One call serves every stat, and a game cannot get it the wrong way round.

With dot-stats

var link := DotAchievementStatsLink.new()
link.tracker = tracker
link.stats = stats_tracker
add_child(link)

dot-stats' recorded signal carries a player's session total, and an achievement is about a lifetime. Wiring the signal straight into record() adds the running session total on every kill: two after the second, five after the third, nine after the fourth. The link holds a baseline and files the difference, and treats a total that goes down as a new session rather than as a negative delta.

Showing them

for row in tracker.listing(player_key):
    print(row["name"], row.get("progress", row.get("unlocked")))

Hidden entries are absent until earned, and secret ones arrive without their description. The filtering happens here rather than in a UI, because a description withheld by the interface that drew it was still sent to the client.

Validating

godot --headless --path . --import
godot --headless --path . res://examples/achievements_selftest.tscn
# 136 checks, all offline. Exits non-zero on any failure.

Licence

MIT. See LICENSE.