0

Description

"At some point you may want to save statistics to Steam's database and \/ or use their achievement system. You will want to [read up about these in Steam's documentation](https:\/\/partner.steamgames.com\/doc\/features\/achievements) as I won't be covering the basics on how to set it up in the Steamworks back-end.\r\n\r\n??? guide Relevant GodotSteam classes and functions\r\n* [User Stats class](https:\/\/godotsteam.com\/classes\/user_stats)\r\n\t* [clearAchievement()](https:\/\/godotsteam.com\/classes\/user_stats#clearachievement)\r\n\t* [getAchievement()](https:\/\/godotsteam.com\/classes\/user_stats#getachievement)\r\n\t* [resetAllStats()](https:\/\/godotsteam.com\/classes\/user_stats#resetallstats)\r\n\t* [setAchievement()](https:\/\/godotsteam.com\/classes\/user_stats#setachievement)\r\n\t* [setStatFloat()](https:\/\/godotsteam.com\/classes\/user_stats#setstatfloat)\r\n\t* [setStatInt()](https:\/\/godotsteam.com\/classes\/user_stats#setstatint)\r\n\t* [storeStats()](https:\/\/godotsteam.com\/classes\/user_stats#storestats)\r\n???\r\n\r\n!!! warning Notes\r\nYou may want to [double-check our Initialization tutorial](https:\/\/godotsteam.com\/tutorials\/initializing) to set up initialization and callbacks functionality if you haven't done so already.\r\n!!!\r\n\r\n## Preparations{.block}\r\n\r\nFirst thing, you'll want to set up your achievements and statistics in the Steamworks back-end. Most importantly, your game does not need to be approved for release nor be released but you want to **publish these changes** live. If not, they will not be exposed to the Steamworks API and you will get errors when trying to retrieve or set them. Once they have been published you can continue on with this tutorial.\r\n\r\n## Getting Statistics And Achievements{.block}\r\n\r\nGodotSteam versions 3.28 \/ 4.14 and newer do not need anything extra to get the local user's statistics and achievements as they are synced automatically by the Steam client at boot thanks to changes in SDK 1.61. In older versions, we had to specifically request them and await a callback to use them.\r\n\r\nIf you are using a GodotSteam version that is 3.27 \/ 4.13 or earlier, [you'll want to look at an older version of this tutorial to set up the functions and callbacks.](https:\/\/codeberg.org\/godotsteam\/godotsteam-docs\/src\/branch\/master\/docs\/tutorials\/stats_achievements.md#getting-steam-statistics-and-achievements) Since we do not have the type of docs that use versioning, you'll have to check it out in repo form.\r\n\r\nFor games like [Skillet](https:\/\/store.steampowered.com\/app\/3013040\/Skillet\/), we want to store our statistic and achievement data somewhere to display and alter so we'll create two dictionary variables to do so, each using the Steam API names as their keys for easy usage:\r\n\r\n```gdscript\r\nvar achievements: Dictionary[String, bool] = {\r\n\t\"achieve1\": false,\r\n\t\"achieve2\": false,\r\n\t\"achieve3\": false\r\n\t}\r\nvar statistics: Dictionary[String, int] = {\r\n\t\"highscore\": 0,\r\n\t\"health\": 0,\r\n\t\"money\": 0\r\n\t}\r\n```\r\n\r\nNext we will create two separate functions after initializtion that will pull and check our data called **load_steam_stats()** and **load_steam_achievements()**:\r\n\r\n```gdscript\r\nfunc initialize_steam() -> void:\r\n var initialize_response: Dictionary = Steam.steamInitEx()\r\n print(\"Did Steam initialize?: %s\" % initialize_response)\r\n\r\n if initialize_response['status'] > Steam.STEAM_API_INIT_RESULT_OK:\r\n print(\"Failed to initialize Steam: %s\" % initialize_response['status'])\r\n return\r\n\r\n load_steam_stats()\r\n load_steam_achievements()\r\n```\r\n\r\nIf you do not plan on displaying the achievements in-game, you can skip that part. Statistics you'll still need to pull to get the current value and modify it for updating though. We will start with statistics.\r\n\r\n### Loading Statistics\r\n\r\n#### Fresh Pull Each Time\r\n\r\nThe cleanest way to get stats is just to pull them fresh from Steam each time the game is loaded. As mentioned earlier, we use the Steam API names as the dictionary keys so we can just loop through the statistics and pull them all:\r\n\r\n```gdscript\r\nfunc load_steam_stats() -> void:\r\n\tfor this_stat in statistics.keys():\r\n\t\tvar stat_value: int = Steam.getStatInt(this_stat)\r\n\t\tprint(\"Retrieved %s stat: %s\" % this_stat, stat_value)\r\n\r\n\t\t# Store the value in our dictionary\r\n\t\tstatistics[this_stat] = stat_value\r\n\tprint(\"Steam statistics loaded\")\r\n```\r\n\r\n#### Load Local File And Compare\r\n\r\nHowever, if we are saving the statistics to a local save file, we will want to check our local copy against Steam's and update everything accordingly:\r\n\r\n```gdscript\r\n# Process statistics\r\nfunc load_steam_stats() -> void:\r\n\tfor this_stat in statistics.keys():\r\n\t\tvar steam_stat: int = Steam.getStatInt(this_stat)\r\n\r\n\t\t# The set_statistic function below in the Setting Statistics section\r\n\t\tif statistics[this_stat] > steam_stat:\r\n\t\t\tprint(\"Stat mismatch; local value is higher (%s), replacing Steam value (%s)\" % [statistics[this_stat], steam_stat])\r\n\t\t\tset_statistic(this_stat, statistics[this_stat])\r\n\r\n\t\telif statistics[this_stat] < steam_stat:\r\n\t\t\tprint(\"Stat mismatch; local value is lower (%s), replacing with Steam value (%s)\" % [statistics[this_stat], steam_stat]))\r\n\t\t\tset_statistic(this_stat, steam_stat)\r\n\r\n\t\telse:\r\n\t\t\tprint(\"Steam stat matches local file: %s\" % this_stat)\r\n\r\n\tprint(\"Steam statistics loaded\")\r\n```\r\n\r\nIf either value is higher, then we call the **set_statistic()** function to smooth that out; this function is down in the [Settings Statistics section.](#setting-statistics) If they are already equal, which they should be, nothing happens and we move on.\r\n\r\n### Loading Achievements\r\n\r\nVery similarly to statistics, we can choose to pull them fresh each time or load in a local copy then compare them to what Steam has.\r\n\r\n#### Fresh Pull Each Time\r\n\r\nWe simply pull the achievement with [**getAchievement()**](https:\/\/godotsteam.com\/classes\/user_stats#getachievement) but check to make sure it even exists in the Steamworks back-end first:\r\n\r\n```gdscript\r\n# Process achievements\r\nfunc load_steam_achievements() -> void:\r\n\tfor this_achievement in achievements.keys():\r\n\t\tvar steam_achievement: Dictionary[bool, bool] = Steam.getAchievement(this_achievement)\r\n\r\n\t\t# Does the achievement actually exist in the Steamworks back-end?\r\n\t\tif not steam_achievement['ret']:\r\n\t\t\tprint(\"Steam does not have this achievement, ignoring it\")\r\n\t\t\tcontinue\r\n\r\n\t\tachievements[this_achievement] = steam_achievement['achieved']\r\n\tprint(\"Steam achievements loaded\")\r\n```\r\n\r\nIf that fails and you are sure you entered the achievement in the Steamworks back-end, there is a good chance you did not publish the changes yet and will have to do so for this to work.\r\n\r\n#### Load Local File And Compare\r\n\r\nJust like with statistics, we will compare our local save file data against what Steam has and make adjustments if necessary:\r\n\r\n```gdscript\r\n# Process achievements\r\nfunc load_steam_achievements() -> void:\r\n\tfor this_achievement in achievements.keys():\r\n\t\tvar steam_achievement: Dictionary = Steam.getAchievement(this_achievement)\r\n\r\n\t\t# Does the achievement actually exist in the Steamworks back-end?\r\n\t\tif not steam_achievement['ret']:\r\n\t\t\tprint(\"Steam does not have this achievement, defaulting to local value: %s\" % achievements[this_achievement])\r\n\t\t\tcontinue\r\n\r\n\t\tif achievements[this_achievement] == steam_achievement['achieved']:\r\n\t\t\tprint(\"Steam achievements match local file, skipping: %s\" % this_achievement)\r\n\t\t\tcontinue\r\n\r\n\t\tset_achievement(this_achievement)\r\n\r\n\tprint(\"Steam achievements loaded\")\r\n```\r\n\r\nThis only triggers our **set_achievement()** function if they are not the same values. You can see that function in the next section below.\r\n\r\n## Setting Achievements{.block}\r\n\r\nSetting the achievements and statistics is pretty simple too. We'll start with achievements. You need to tell Steam the achievement is unlocked and then store it so it visually 'pops' in overlay. For this we will create two functions, one for achievements and the other for storing things and popping those achievements:\r\n\r\n```gdscript\r\nfunc set_achievement(this_achievement: String) -> void:\r\n\tif not achievements.has(this_achievement):\r\n\t\tprint(\"This achievement does not exist locally: %s\" % this_achievement)\r\n\t\treturn\r\n\tachievements[this_achievement] = true\r\n\r\n\tif not Steam.setAchievement(this_achievement):\r\n\t\tprint(\"Failed to set achievement: %s\" % this_achievement)\r\n\t\treturn\r\n\r\n\tprint(\"Set acheivement: %s\" % this_achievement)\r\n\tstore_steam_data()\r\n\r\n\r\nfunc store_steam_data() -> void:\r\n\tif not Steam.storeStats():\r\n\t\tprint(\"Failed to store data on Steam, should be stored locally\")\r\n\t\treturn\r\n\tprint(\"Data successfully sent to Steam\")\r\n```\r\n\r\nIf we don't call [**storeStats()**](https:\/\/godotsteam.com\/classes\/user_stats#storestats) the achievement pop-up won't trigger but the achievement should be recorded. However, we will still have to call [**storeStats()**](https:\/\/godotsteam.com\/classes\/user_stats#storestats) at some point to upload them.\r\n\r\n!!! warning Notes\r\nIn Godot 4.x with the introduction of Vulkan, depending on a variety of factors, your Steam overlay may not be working correctly so you will not see this pop. Rest assured, when run from the Steam client this will work correctly though.\r\n!!!\r\n\r\n## Setting Statistics{.block}\r\n\r\nStatistics follow a pretty similar process; both int and float based ones. How much and whether or not you are setting the full value or just an increment is all handled in the Steamworks back-end, [outlined in Valve's docs here.](https:\/\/partner.steamgames.com\/doc\/features\/achievements#3)\r\n\r\nFor our example, as we do in Skillet, we will just be incrementing the value by 1 so we don't need to worry about the previous stat value:\r\n\r\n```gdscript\r\nfunc set_statistic(this_stat: String, new_value: int = 1) -> void:\r\n\tif not Settings.statistics.has(this_stat):\r\n\t\tprint(\"This statistic does not exist locally: %s\" % this_stat)\r\n\t\treturn\r\n\t# Set our local version\r\n\tSettings.statistics[this_stat] += new_value\r\n\r\n\t# Set Steam's version\r\n\tif not Steam.setStatInt(this_stat, new_value):\r\n\t\tprint(\"Failed to set stat %s to: %s\" % [this_stat, new_value])\r\n\t\treturn\r\n\r\n\tprint(\"Set statistics %s succesfully: %s\" % [this_stat, new_value])\r\n\tstore_steam_data()\r\n```\r\n\r\nYou can see we call our **store_steam_data()** function like when setting achievements. This isn't necessary to do each call, you can just do this at the end when a user is quitting the game.\r\n\r\n!!! warning Notes\r\nIf your stat is configured as \"increment only\", setting the value to a new and lower value will cause you to get a **false** response when setting.\r\n!!!\r\n\r\n## Resetting Stats And Achievements{.block}\r\n\r\nThough it is best used for testing prior to release, I will often allow users to reset their statistics and achievements in the Options section of the game. To do this, you just need to call one specific function, **[resetAllStats()](https:\/\/godotsteam.com\/classes\/user_stats#resetallstats)**. Passing **true** to this function will reset the achievements too; in case you want to reset both:\r\n\r\n```gdscript\r\nfunc reset_statistics() -> void:\r\n\tprint(\"Resetting all statistics and achievements for local user\")\r\n\tif not Steam.resetAllStats(true):\r\n\t\tprint(\"Failed to reset statistics and achievements\")\r\n```\r\n\r\nAlternatively, you may want to clear an achievement instead of all your statistics. In this case, we will use **[clearAchievement()](https:\/\/godotsteam.com\/classes\/user_stats#clearachievement)** instead:\r\n\r\n```gdscript\r\nfunc reset_achievement(this_achievement: String) -> void:\r\n\tprint(\"Resetting achievement %s\" % this_achievement)\r\n\tif not Steam.clearAchievement(this_achievement):\r\n\t\tprint(\"Failed to reset achievement: %s\" % this_achievement)\r\n```\r\n\r\n## More Yet{.block}\r\n\r\nThere are a variety of additional functions for statistics and achievements this tutorial does not cover like settings \/ getting stats and achievement for other users than the local one, getting the icons or descriptions from Steam for achievements, global stats, etc. [You can read more about them in our docs here](https:\/\/godotsteam.com\/classes\/user_stats#functions) or [check out Skillet's codebase to see some implmentations.](https:\/\/codeberg.org\/godotsteam\/skillet)\r\n\r\nThat's it for now!\r\n\r\n## Additional Resources{.block}\r\n\r\n### Video Tutorials\r\n\r\nPrefer video tutorials? Feast your eyes and ears!\r\n\r\n[youtube: Godot + Steam tutorial](https:\/\/www.youtube.com\/watch?v=J0GrG-AffCI&t=571s){ data-author=\"BluePhoenixGames\" }\r\n\r\n[youtube: How Achievements Are Done](https:\/\/www.youtube.com\/watch?v=VCwNxfYZ8Cw&t=938s){ data-author=\"FinePointCGI\" }\r\n\r\n[youtube: Let's Talk About Statistics](https:\/\/www.youtube.com\/watch?v=VCwNxfYZ8Cw&t=1504s){ data-author=\"FinePointCGI\" }\r\n\r\n[youtube: Godot 4 Steam Achievements](https:\/\/www.youtube.com\/watch?v=dg6fSBe5EEE){ data-author=\"Gwizz\" }\r\n\r\n### Example Project\r\n\r\n[You can view this tutorial in action with more in-depth information by checking out our upcoming free-to-play game Skillet on GitHub.](https:\/\/codeberg.org\/godotsteam\/skillet) This link will take you to the direct file where this tutorial comes from but feel free to explore the rest of the project too!\r\n"

Main code

var achievements: Dictionary[String, bool] = {
	"achieve1": false,
	"achieve2": false,
	"achieve3": false
	}
var statistics: Dictionary[String, int] = {
	"highscore": 0,
	"health": 0,
	"money": 0
	}


func initialize_steam() -> void:
    var initialize_response: Dictionary = Steam.steamInitEx()
    print("Did Steam initialize?: %s" % initialize_response)

    if initialize_response['status'] > Steam.STEAM_API_INIT_RESULT_OK:
        print("Failed to initialize Steam: %s" % initialize_response['status'])
        return

    load_steam_stats()
    load_steam_achievements()


func load_steam_stats() -> void:
	for this_stat in statistics.keys():
		var stat_value: int = Steam.getStatInt(this_stat)
		print("Retrieved %s stat: %s" % this_stat, stat_value)

		# Store the value in our dictionary
		statistics[this_stat] = stat_value
	print("Steam statistics loaded")


func load_steam_achievements() -> void:
	for this_achievement in achievements.keys():
		var steam_achievement: Dictionary[bool, bool] = Steam.getAchievement(this_achievement)

		# Does the achievement actually exist in the Steamworks back-end?
		if not steam_achievement['ret']:
			print("Steam does not have this achievement, ignoring it")
			continue

		achievements[this_achievement] = steam_achievement['achieved']
	print("Steam achievements loaded")


func set_achievement(this_achievement: String) -> void:
	if not achievements.has(this_achievement):
		print("This achievement does not exist locally: %s" % this_achievement)
		return
	achievements[this_achievement] = true

	if not Steam.setAchievement(this_achievement):
		print("Failed to set achievement: %s" % this_achievement)
		return

	print("Set acheivement: %s" % this_achievement)
	store_steam_data()


func store_steam_data() -> void:
	if not Steam.storeStats():
		print("Failed to store data on Steam, should be stored locally")
		return
	print("Data successfully sent to Steam")


func set_statistic(this_stat: String, new_value: int = 1) -> void:
	if not Settings.statistics.has(this_stat):
		print("This statistic does not exist locally: %s" % this_stat)
		return
	# Set our local version
	Settings.statistics[this_stat] += new_value

	# Set Steam's version
	if not Steam.setStatInt(this_stat, new_value):
		print("Failed to set stat %s to: %s" % [this_stat, new_value])
		return

	print("Set statistics %s succesfully: %s" % [this_stat, new_value])
	store_steam_data()


func reset_statistics() -> void:
	print("Resetting all statistics and achievements for local user")
	if not Steam.resetAllStats(true):
		print("Failed to reset statistics and achievements")


func reset_achievement(this_achievement: String) -> void:
	print("Resetting achievement %s" % this_achievement)
	if not Steam.clearAchievement(this_achievement):
		print("Failed to reset achievement: %s" % this_achievement)

Comments