Progression Tracking

Track player progression through levels, quests, tutorials, or any sequential content. The SDK automatically calculates duration between start and completion/failure.

Why Progression Tracking?

Progression data reveals your difficulty curve. Find levels where too many players fail, stages that take too long, and content that nobody reaches. Fix these and your retention improves. See the Analytics Guide for reading progression data in the dashboard.

Functions

start_progression()

QuestData.start_progression(location: String, tier: String = "")

Parameter	Type	Default	Description
location	String	required	Level or area identifier (e.g. "level_5", "tutorial", "boss_dragon")
tier	String	""	Optional difficulty or sub-category (e.g. "hard", "nightmare")

Starts tracking time for this progression. Internally sends a progression_start event.

complete_progression()

QuestData.complete_progression(location: String, score: int = 0)

Parameter	Type	Default	Description
location	String	required	Must match the location from start_progression()
score	int	0	Optional score achieved

Completes the progression and automatically calculates the duration since start_progression() was called. Sends a progression_complete event.

fail_progression()

QuestData.fail_progression(location: String, reason: String = "dead")

Parameter	Type	Default	Description
location	String	required	Must match the location from start_progression()
reason	String	"dead"	Why the player failed (e.g. "timeout", "out_of_moves")

Fails the progression and calculates duration. Sends a progression_fail event.

Example

# Player enters a level
func _on_level_entered(level_name: String, difficulty: String):
    QuestData.start_progression(level_name, difficulty)

# Player beats the level
func _on_level_completed(level_name: String, score: int):
    QuestData.complete_progression(level_name, score)

# Player dies or runs out of time
func _on_level_failed(level_name: String, reason: String):
    QuestData.fail_progression(level_name, reason)

Tutorial Flow

# Track tutorial steps as progressions
QuestData.start_progression("tutorial_movement")
# ... player completes movement tutorial ...
QuestData.complete_progression("tutorial_movement")

QuestData.start_progression("tutorial_combat")
# ... player skips combat tutorial ...
QuestData.fail_progression("tutorial_combat", "skipped")

How It Works

1. start_progression() records the current timestamp internally
2. When complete_progression() or fail_progression() is called, the SDK calculates duration_seconds automatically
3. The event properties include location, tier (if set), duration_seconds, and score/reason
4. If complete_progression() is called without a matching start_progression(), the duration will be 0

Event Properties

The SDK sends these properties automatically:

Event	Properties
progression_start	location, tier
progression_complete	location, tier, duration_seconds, score
progression_fail	location, tier, duration_seconds, reason

Dashboard

View progression data in the dashboard under Analytics > Dashboard. The overview shows:

• Completion rates per level
• Average duration per level
• Most common failure reasons
• Difficulty distribution

Best Practices

1. Use consistent location names — "level_5" is better than "Level 5" or "lvl5"
2. Always call start before complete/fail — Without a start, duration is 0
3. Use tier for difficulty — This lets you compare completion rates across difficulties
4. Track boss fights as progressions — Great for finding difficulty spikes