Skip to content
Quest Data Docs

Dodge the Creeps Walkthrough

This walkthrough shows the minimum viable Quest Data integration for a Godot game, using the official “Dodge the Creeps” tutorial as the playground. Three things, in order:

  1. Plugin setup — getting QuestData available in your scripts
  2. Event tracking — recording what your players do
  3. Leaderboards — competitive scoreboards in 2 lines

That’s it. The actual main.gd in the demo does more (achievements, cloud saves, remote config, heatmap), but none of that is required for a useful first integration. Once you’ve shipped these three pieces and seen data flowing, expand from the SDK reference — pick the next feature your game actually needs.

1 · Plugin setup

Section titled “1 · Plugin setup”

The demo ships with the Quest Data plugin pre-installed under addons/quest_data/ and pre-enabled in project.godot. For your own game you’d:

  1. Download the SDK from wolke.digitalfactory.at/index.php/s/t7zP3PP6wGD9jQt (or GitHub Releases) and drop addons/quest_data/ into your project
  2. Enable it under Project → Project Settings → Plugins
  3. Configure the API key (next step)

Open examples/dodge-the-creeps/project.godot and look for the [quest_data] block:

[quest_data]
api_key="b30e7fd6a9c1cdb3db19b9fc18b0ef71"
dev_api_url="http://localhost:3010/v1/track"
prod_api_url="https://quest-api.digitalfactory.at/v1/track"

The API key tells the backend which game the events belong to. The default b30e7fd6... is the seeded demo key — for your own game, generate one in the dashboard under Configuration → API Keys at quest-data-seven.vercel.app. dev_api_url zeigt auf den lokalen Backend-Container (docker compose up), prod_api_url auf das gehostete Backend unter https://quest-api.digitalfactory.at.

The plugin registers itself as an autoload singleton named QuestData, available globally:

# In any script, anywhere — no imports, no instantiation
QuestData.track("my_event")

If QuestData.track(...) errors with “Identifier not declared” → the plugin isn’t enabled. Fix that first, restart Godot.

For the full installation guide on a fresh project, see Godot SDK Setup.

2 · Event tracking

Section titled “2 · Event tracking”

Events are how you tell Quest Data what’s happening in your game. Each event has a name and an optional payload.

The demo tracks two kinds of events: app start (when the game launches) and game over (when the player dies).

App start (main.gd:_ready())

Section titled “App start (main.gd:_ready())”
main.gd
func _ready():
    QuestData.track("app_start", {
        "game": "dodge_the_creeps",
        "version": "1.0.0",
    })

Fire this once on launch. The dashboard uses it to know when a session began. Keep the payload small — game name, version, anything you’d want to filter sessions by later.

Game over (main.gd:game_over())

Section titled “Game over (main.gd:game_over())”
main.gd
func game_over():
    var duration = Time.get_ticks_msec() / 1000.0 - _game_start_time


    QuestData.track("game_over", {
        "score": score,
        "duration_seconds": snappedf(duration, 0.1),
    })

This is the workhorse pattern: when something interesting happens, ship an event with the relevant numbers attached.

Two rules of thumb

Section titled “Two rules of thumb”
  1. Track milestones, not every input. game_over with the final score is useful. Tracking every keypress isn’t — it floods the dashboard and tells you nothing your physics code couldn’t.
  2. Always include the numbers you’ll want to query later. Adding score and duration_seconds to game_over lets you build “average run length” or “score distribution” charts later. Adding them retroactively means waiting weeks for new data to accumulate.

Where to see the events

Section titled “Where to see the events”

After playing a round, open the dashboard at http://localhost:3001, select Dodge the Creeps, and head to Live Feed. You’ll see your events streaming in within seconds.

For the full event API (custom events, properties, batching), see Event Tracking.

3 · Leaderboards

Section titled “3 · Leaderboards”

Leaderboards turn one tracked number into a competitive scoreboard, visible to all players. Two lines.

Submitting a score (main.gd:game_over())

Section titled “Submitting a score (main.gd:game_over())”
main.gd
func game_over():
    # ... game state cleanup ...


    QuestData.submit_score("highscore", score)

That’s the entire integration. The first argument is the board name (you can have multiple — highscore, survival_time, weekly_*); the second is the score.

Why both track("game_over") and submit_score("highscore")?

Section titled “Why both track("game_over") and submit_score("highscore")?”

Looks redundant at first. It’s not:

  • track("game_over", {score}) lets you build histograms and trends (“most players score between 10 and 30”)
  • submit_score("highscore", score) lets you show rankings (“you’re 47th out of 1284”)

Different jobs. Cheap to do both — the SDK batches the calls.

Server-side dedup

Section titled “Server-side dedup”

submit_score uses UPSERT semantics on the backend: it only updates a player’s leaderboard entry if the new score beats their current one. You don’t need client-side “is this a new highscore?” guards.

Where to see the leaderboard

Section titled “Where to see the leaderboard”

Dashboard → Leaderboards → highscore. Your runs appear sorted by score.

For metadata (filtering by song, level, character class) and weekly/monthly leaderboards, see Leaderboards.

You’re done

Section titled “You’re done”

Three calls (track("app_start"), track("game_over"), submit_score("highscore")) — that’s a complete, useful integration. Play a few rounds, watch the dashboard, decide what to add next.

Add a few more events?

Section titled “Add a few more events?”

Once the basics are flowing, the next 5–10 events are where you actually start learning about your players. The Event Ideas (Action Game) cookbook covers the eight events that earn their bandwidth — retention signals (player_respawn), balancing signals (mob_spawned density at death, score_milestone drop-off, movement_pattern heatmap), perf signals (fps_drop). All wired live in this same demo.

What’s also in the demo

Section titled “What’s also in the demo”

The demo’s main.gd is longer than the snippets above because it also exercises Quest Data’s optional features: cloud saves, achievements, remote config, heatmap events, error tracking, remote logging. Each of those is a worthwhile integration on its own — but none of them are required to start getting value from the SDK.

When you’re ready to add one, pick the dedicated walkthrough or reference:

FeatureWhy you might add itWhere to learn it
Cloud SavesPersist player progress across devicesSave / Load Demo Walkthrough
HeatmapSpot where players struggle on a level2D Platformer Walkthrough · Spatial Tracking
Remote ConfigLive-tune balance without shipping an updateRemote Config
AchievementsUnlockable goals visible to playersAchievements
Error TrackingProduction crash + 60s pre-crash telemetryError Tracking

Read the demo’s main.gd once you’ve shipped your own first three calls — it’ll make a lot more sense as a menu of things you could add rather than a wall of features to digest at once.

Next Steps

Section titled “Next Steps”