Skip to main content

Stats

Talo stats let you track individual player data as well as aggregated global data - like how many items have been crafted or how many deaths a player has.

To create a stat, head over to the dashboard, visit the stats page and create your first stat. Take note of the Internal name as this is how you'll be referring to your stat.

tip

Check out this blog post on how to track player stats in Godot for a detailed walkthrough

Getting stats​

read:gameStats

You can list all available stats using Talo.stats.get_stats(). This will return all the constraint data defined in the dashboard like the default_value, max_change and max_value. This will also return the global values for global stats:

var res := await Talo.stats.get_stats()
var all_stats := PackedStringArray(res.map(func(item: TaloStat): return item.internal_name))
var internal_names := ", ".join(all_stats)

## e.g. Stats: gold-collected, health-healed, deaths
print("Stats: %s" % [internal_names])

Fetching individual stats​

If you already have the internal name of a stat, you can use Talo.stats.find() and pass in the internal name to return data for a single stat.

Tracking stats​

write:gameStats

You can track a stat using the Stats API track() function which takes your stat's internal_name and the amount to change the stat by (default 1.0):

player.gd
func on_death() -> void:
	Talo.stats.track('deaths')
player_potion.gd
var health: float

func on_heal(potion: Potion) -> void:
	health += potion.amount
	Talo.stats.track('health-healed', potion.amount)

Stat values​

After updating a stat using track(), you can check the updated value for the player stat and global stat:

var res := await Talo.stats.track(stat_name)
print("%s, %s" % [res.value, res.stat.global_value])

Find a stat value​

read:gameStats

You can also get the current value of a stat for a player using Talo.stats.find_player_stat().

Listing player stat values​

read:gameStats

If you need to find all player stat values for the current player, you can use Talo.stats.list_player_stats(). This function returns a list of player stats which include the value and related stat:

var res := await Talo.stats.list_player_stats()
var values := PackedStringArray(
	res.map(
		func (item: TaloPlayerStat): return "%s = %s" % [item.stat.internal_name, item.value]
	)
)
var player_stat_values := ", ".join(values) if values.size() > 0 else "none"
print("Player stats: %s" % [player_stat_values]) # Player stats: deaths = 5, health-healed = 200

The function above iterates through the player stats returned by the API and pick out the stat.internal_name and value.

Stat history​

read:gameStats

You can fetch a history of updates to a stat for the current player using Talo.stats.get_history(). These results are paginated and can be filtered by specific start and end dates:

func fetch_history() -> void:
	var res := await Talo.stats.get_history(stat_name)
	var changes := PackedStringArray(res.history.map(func(item): return str(item.change)))

	# e.g. "gold-collected changed by 100, 46, 82, 19, 104"
	print("%s changed by: %s" % [stat_name, ", ".join(changes)])

Filtering stat history​

The get_history() function accepts the following optional parameters:

  • page: Page number for pagination (default: 0)
  • start_date: Filter to show only changes tracked on or after this date. This can be a UTC Date (YYYY-MM-DD), DateTime (ISO 8601), or millisecond timestamp
  • end_date: Filter to show only changes tracked on or before this date. This can be a UTC Date (YYYY-MM-DD), DateTime (ISO 8601), or millisecond timestamp
# Get the second page of history
var res := await Talo.stats.get_history(stat_name, 1)

# Get history for September 2025
var res := await Talo.stats.get_history(stat_name, 0, "2025-09-01", "2025-09-30")

# Get all history since a specific date
var res := await Talo.stats.get_history(stat_name, 0, "2025-09-15")

Global stat history​

read:gameStats

For global stats, you can also fetch a history of updates from all players using Talo.stats.get_global_history(). This API returns metrics about the stat during the filtered time period and can be filtered by player, date range, and pagination:

func fetch_global_history() -> void:
	var res := await Talo.stats.get_global_history(stat_name)
	var total_updates := res.count
	var global_metrics := res.global_value
	var player_metrics := res.player_value

	print("Total: %s, Min: %s, max: %s, median: %s, average: %s, average change: %s, average player value: %s" % [
		total_updates,
		global_metrics.min_value,
		global_metrics.max_value,
		global_metrics.median_value,
		global_metrics.average_value, # average global value
		global_metrics.average_change,
		player_metrics.average_value # average player value
	])

Filtering global stat history​

The get_global_history() function accepts the following optional parameters:

  • page: Page number for pagination (default: 0)
  • player_id: Filter to show only changes from a specific player ID
  • start_date: Filter to show only changes tracked on or after this date. This can be a UTC Date (YYYY-MM-DD), DateTime (ISO 8601), or millisecond timestamp
  • end_date: Filter to show only changes tracked on or before this date. This can be a UTC Date (YYYY-MM-DD), DateTime (ISO 8601), or millisecond timestamp
# Get global history for a specific player
var res := await Talo.stats.get_global_history(stat_name, 0, "player-123")

# Get global history for September 2025
var res := await Talo.stats.get_global_history(stat_name, 0, "", "2025-09-01", "2025-09-30")

# Get global history for a specific player in a date range
var res := await Talo.stats.get_global_history(stat_name, 0, "player-123", "2025-09-01", "2025-09-30")

# Get the second page of global history
var res := await Talo.stats.get_global_history(stat_name, 1)