How do I unlock a Steam achievement and set a stat from Godot 4?
Call three functions on the Steam singleton: setAchievement() with the API name of the achievement, setStatInt() or setStatFloat() with the API name of the stat and its new value, then storeStats(). The first two calls change only the in-memory state of Steam. storeStats() sends the data to the server and shows the achievement notification.
Three conditions apply. Steam must be initialised, so steamInitEx() returned status 0. The achievement and the stat must exist in the Steamworks settings of your app, and you must have published those settings. The names in the code must be the API names, not the display names. The names below are examples.
Each function returns a bool. setAchievement() and the two stat functions return false when the API name does not exist or the changes are not published. The sections below give a full autoload script, with the checks.
GDScript
# After Steam.steamInitEx() returns status 0 (see the autoload below):
Steam.setAchievement("ACH_FIRST_BOSS") # unlock, in memory only
Steam.setStatInt("STAT_BOSSES_DEFEATED", 1) # an absolute value, not an increment
Steam.storeStats() # upload; this shows the pop-upSources: GodotSteam documentation, User Stats class and Stats And Achievements tutorial; Steamworks documentation, ISteamUserStats.
Which GodotSteam and Godot versions does this guide use?
GodotSteam 4.24 on Godot 4, built on Steamworks SDK 1.65. That is the version the GodotSteam site listed for Godot 4.x on 19 November 2026. The pre-compiled bundle and the GDExtension use the same code base, so the code here is the same for the two.
The API changed in earlier versions, and the table gives the changes that the GodotSteam changelog records. The largest change is the removal of requestCurrentStats(). Valve marks RequestCurrentStats as deprecated: the Steam client loads the stats and achievements of your game before launch, so you do not request them.
The GodotSteam pages do not agree on the exact version of that change. The changelog and the class reference say that requestCurrentStats() and the current_stats_received signal went in 4.12. The stats tutorial says that 4.14 and newer need nothing extra. Notes in the class reference say that versions before SDK 1.60 (GodotSteam 4.9) must call it. If your project uses a version from 4.9 to 4.13, read the changelog of that version.
We did not find a Steam Deck section in the GodotSteam stats pages, so this guide has none. One related change is documented: version 4.21 removed isSteamRunningOnSteamDeck().
| GodotSteam version | Change |
|---|---|
| 4.4 | steamInitEx() added. It returns a dictionary with status and verbal. |
| 4.5 | steamInit() and steamInitEx() get arguments for the app ID and for internal callbacks. |
| 4.9 | Updated for Steamworks SDK 1.60. |
| 4.12 | The current_stats_received callback is removed. The first argument of steamInit() and steamInitEx() no longer requests stats. |
| 4.14 | Steamworks SDK 1.62. The stats argument is removed, so the app ID is the first argument. Project Settings for the app ID, auto-initialization and embedded callbacks are added. The tutorial says embedded callbacks were broken in this version. |
| 4.15 | Embedded callbacks fixed. |
| 4.21 | Steamworks SDK 1.65. isSteamRunningOnSteamDeck() removed. |
| 4.24 | The version this guide targets. |
Sources: GodotSteam documentation, What Are You Actually Making?, Godot 4.x changelog, User Stats class, Initializing Steam and Stats And Achievements tutorials; Steamworks documentation, ISteamUserStats.
What do I need before I start?
You need a Steamworks app ID, the Steam client running with an account that owns the app, and one GodotSteam flavour in your Godot 4 project. GodotSteam says that the two Godot 4 flavours behave the same, and that both give you the Steam object globally. Do not mix them: the common issues page says that the pre-compiled editor plus the plug-in gives duplicate calls and errors.
Steam must know the app ID when the game does not start from the Steam client. GodotSteam gives four methods: the Project Settings under Steam, Initialization (from 4.14); the first argument of steamInitEx(); the SteamAppId and SteamGameId environment variables; or a steam_appid.txt file. GodotSteam does not recommend the file. Valve says that the file contains only the app ID, sits next to the executable, and must not ship in your builds.
Without your own app ID, GodotSteam suggests app ID 480, Valve's Spacewar example. You cannot test your own achievements with it, because achievements belong to one app.
GodotSteam has no C# version. Its C# tutorial points to community C# bindings for the GDExtension, which we did not test.
| Flavour | Install | Export | Files to ship |
|---|---|---|---|
| Pre-compiled bundle | Download the bundle from the GodotSteam releases page. It contains a Godot editor with GodotSteam built in, and export templates. | Set the GodotSteam templates as the custom templates in the export dialog. A standard template gives the parse error: The identifier "Steam" isn't declared in the current scope. | The game, the .pck file and the Steam API file: steam_api64.dll on 64-bit Windows, libsteam_api.so on Linux. |
| GDExtension | Get the GodotSteam GDExtension from the Godot asset store page that the GodotSteam site links to. Put the addons/godotsteam folder in the project root. You do not enable it; it is present when the folder is there. | Use the standard Godot export templates. Do not use the GodotSteam templates. | The game, the .pck file, the GodotSteam library that Godot exports (godotsteam.dll, libgodotsteam.so or libgodotsteam.dylib) and the Steam API file. |
| Your own build | Compile the module into Godot, or compile the GDExtension, with the Steamworks SDK from the partner site. | Your own templates for the module; standard templates for the GDExtension. | The same files as the matching row above. |
Sources: GodotSteam documentation, Getting Started, What Are You Actually Making?, Compiling The GodotSteam GDExtension, Exporting and Shipping, Initializing Steam, Common Issues and C-Sharp; Steamworks documentation, Steamworks API Overview.
How do I define achievements and stats in Steamworks?
Define them in the Steamworks settings of your app, then publish. Each achievement and each stat has an API Name, and that string is what your GDScript passes to GodotSteam. Valve's example of an achievement API name is ACH_WIN_ONE_GAME.
A stat has one of three types, as in the table. A stat also has optional limits: Increment Only, Max Change, Min Value, Max Value and Default Value. Set Aggregated if you want Steam to keep a global total. An achievement can have a Progress Stat with a Stat Range that maps to 0% and 100% progress.
Nothing works until you publish. GodotSteam says that the game does not need to be released or approved, but unpublished achievements and stats are not exposed to the API. Valve also says that games are limited to 100 achievements at first.
- Open your app in Steamworks and select Edit Steamworks Settings.
- In the Stats & Achievements section, create each stat: choose the type, the API Name and the limits.
- Select Stats & Achievements, Achievements, and open the achievements editor. Create each achievement with an API Name, a display name, a description and the icons.
- For a progress achievement, choose the Progress Stat and its Stat Range. The stat must exist first.
- Publish the changes from the Publish tab in Edit Steamworks Settings.
| Stat type | What Valve says it is | GodotSteam write function |
|---|---|---|
| INT | A 32-bit (signed) integer, for example the number of games played. | setStatInt(stat_name, value) |
| FLOAT | A 32-bit floating point value, for example the number of miles driven. | setStatFloat(stat_name, value) |
| AVGRATE | A moving average over a window that you set on the stat. | updateAvgRateStat(stat_name, this_session, session_length) |
Sources: Steamworks documentation, Stats and Achievements and Step by Step: Achievements; GodotSteam documentation, Stats And Achievements tutorial.
How do I initialise Steam in a Godot 4 project?
Call Steam.steamInitEx() once, in an autoload script, and call Steam.run_callbacks() in _process(). steamInitEx() returns a dictionary with two keys: status and verbal. Status 0 (STEAM_API_INIT_RESULT_OK) means success, 1 is another failure, 2 means the game cannot connect to Steam, and 3 means the Steam client is out of date.
The two arguments are optional: app_id and embed_callbacks. With an app ID, GodotSteam sets the SteamAppId and SteamGameId environment variables for you. With embed_callbacks set to true, GodotSteam runs the callbacks internally. This guide calls run_callbacks() in _process() instead, because that is the method the tutorial says worked in every version.
When Steam does not start, the script below keeps steam_ready false and every later function does nothing. So the same build also runs outside Steam. GodotSteam says most failures come from a missing Steam API file or a missing app ID.
steamInit() takes the same arguments and returns only true or false. From 4.14 you can also turn on auto-initialization in the Project Settings and read the result with get_steam_init_result().
GDScript: steamworks.gd (autoload)
# steamworks.gd
# Add it under Project, Project Settings, Globals, Autoload, with the name Steamworks.
# Targets GodotSteam 4.24 (Steamworks SDK 1.65) on Godot 4.
extends Node
# 480 is Spacewar, Valve's example app. Replace it with your own App ID.
const APP_ID: int = 480
var steam_ready: bool = false
func _ready() -> void:
# Keep callbacks running when the game is paused.
process_mode = Node.PROCESS_MODE_ALWAYS
var result: Dictionary = Steam.steamInitEx(APP_ID)
steam_ready = result["status"] == Steam.STEAM_API_INIT_RESULT_OK
if not steam_ready:
# 1: other failure. 2: no Steam client. 3: Steam client out of date.
push_warning("Steam did not start (%s): %s" % [result["status"], result["verbal"]])
func _process(_delta: float) -> void:
if steam_ready:
Steam.run_callbacks()Sources: GodotSteam documentation, Initializing Steam tutorial and Main class; GodotSteam source code, godotsteam.cpp.
How do I unlock an achievement?
Set it, then store it. setAchievement() unlocks the achievement in the memory of Steam only. storeStats() sends the unlock to the server and triggers the overlay notification. Valve and GodotSteam both say that storeStats() is required to display the notification, so call it soon after setAchievement().
You can set an achievement that is already unlocked. Valve says that you can unlock an achievement multiple times, so you do not need to check first.
If the process ends with changes that you did not store, Steam stores them at exit. Do not depend on that for the notification: the player sees the pop-up only when you call storeStats() in the game.
GDScript
# In steamworks.gd
func unlock(achievement: String) -> void:
if not steam_ready:
return
# Step 1: set. This changes only the in-memory state of Steam.
if not Steam.setAchievement(achievement):
push_warning("No published Steam achievement has the API name %s" % achievement)
return
# Step 2: store. This uploads the unlock and shows the overlay notification.
if not Steam.storeStats():
push_warning("storeStats() failed. Are the stats of this app published?")
# From any script in the game:
# Steamworks.unlock("ACH_FIRST_BOSS")Sources: Steamworks documentation, ISteamUserStats (SetAchievement, StoreStats); GodotSteam documentation, User Stats class and Stats And Achievements tutorial.
How do I read whether an achievement is unlocked?
Call Steam.getAchievement() with the API name. It returns a dictionary with two keys. ret is true if the API name exists in Steamworks and the changes are published. achieved is true if the player has the achievement. On GodotSteam 4.24 you can call it directly after initialisation, with no request first.
getAchievementAndUnlockTime() returns three keys: retrieve, achieved and unlocked. Note that its first key is retrieve, not ret. unlocked is the unlock time in seconds since 1 January 1970 UTC.
To show the achievements in your own menu, getAchievementDisplayAttribute() returns the localised name with the key name, the description with desc, and "0" or "1" with hidden. getAchievementIcon() returns an image handle; GodotSteam has a separate Achievement Icons tutorial.
Valve says that Steam keeps a local cache of this data, so the calls also work in offline mode, and your game does not need its own copy on disk.
GDScript
# In steamworks.gd
func is_unlocked(achievement: String) -> bool:
if not steam_ready:
return false
var state: Dictionary = Steam.getAchievement(achievement)
# ret: the API name exists and is published. achieved: the player has it.
return state.get("ret", false) and state.get("achieved", false)
func unlock_time(achievement: String) -> int:
if not steam_ready:
return 0
var state: Dictionary = Steam.getAchievementAndUnlockTime(achievement)
if not state.get("retrieve", false) or not state.get("achieved", false):
return 0
return state.get("unlocked", 0) # Unix time, in seconds
func display_name(achievement: String) -> String:
if not steam_ready:
return ""
return Steam.getAchievementDisplayAttribute(achievement, "name") # or "desc", "hidden"Sources: GodotSteam documentation, User Stats class; GodotSteam source code, godotsteam.cpp; Steamworks documentation, Stats and Achievements.
How do I set and read Steam stats (INT and FLOAT)?
Read with getStatInt() or getStatFloat(), write with setStatInt() or setStatFloat(), then call storeStats(). The value that you write is absolute. The class reference and Valve both say that Steam does not increment or decrement for you. So to add 1, read the value, add 1, and write the total.
The type must match. Valve says that SetStat returns false if the type that you pass is not the type in Steamworks. The write also returns false if the stat does not exist or is not published. GodotSteam adds that an Increment Only stat returns false when you set a lower value.
Do not call storeStats() often. Valve says that the call can be rate limited, and that the frequency should be on the order of minutes, not seconds: the end of a round, a map change or a checkpoint. The set calls are cheap, and Valve says that Steam keeps their values if the game crashes.
For an AVGRATE stat, call updateAvgRateStat() with the amount since the last call and the time since the last call. Use the same time unit as the Window of the stat.
GDScript
# In steamworks.gd
func add_to_int_stat(stat: String, amount: int = 1) -> void:
if not steam_ready:
return
# setStatInt() takes the new total, so read the current value first.
var total: int = Steam.getStatInt(stat) + amount
if not Steam.setStatInt(stat, total):
push_warning("Steam refused the INT stat %s" % stat)
func set_float_stat(stat: String, value: float) -> void:
if not steam_ready:
return
if not Steam.setStatFloat(stat, value):
push_warning("Steam refused the FLOAT stat %s" % stat)
func get_float_stat(stat: String) -> float:
if not steam_ready:
return 0.0
return Steam.getStatFloat(stat)
# Call this at a checkpoint or at the end of a level, not on each frame.
func save_to_steam() -> void:
if steam_ready and not Steam.storeStats():
push_warning("storeStats() failed")
# From the game:
# Steamworks.add_to_int_stat("STAT_ENEMIES_DEFEATED")
# Steamworks.set_float_stat("STAT_BEST_LAP_SECONDS", 83.4)
# Steamworks.save_to_steam()Sources: Steamworks documentation, ISteamUserStats (SetStat, StoreStats, UpdateAvgRateStat) and Stats and Achievements; GodotSteam documentation, User Stats class and Stats And Achievements tutorial.
How do I show progress for an achievement that is tied to a stat?
Give the achievement a Progress Stat in Steamworks, update that stat from the game, and call indicateAchievementProgress() at a milestone. The function takes the achievement API name, the current progress and the maximum progress, and shows a progress notification. Valve's example is 20 wins, with one call at 10 wins.
The call does not change anything. Valve and GodotSteam both say that it does not set the progress and does not unlock the achievement; your game does that with the stat functions. It returns false if the achievement does not exist, if it is already unlocked, or if the current progress is not less than the maximum.
Valve's pages describe the Progress Stat as the source of the progress bar. They do not say that Steam unlocks the achievement when the stat reaches the maximum. So the code below calls setAchievement() at the target, which is safe in the two cases.
If you do not want the target in your code, getAchievementProgressLimitsInt() and getAchievementProgressLimitsFloat() return a dictionary with min and max for the achievement.
GDScript
# In steamworks.gd
# In Steamworks, ACH_DEFEAT_10_BOSSES has STAT_BOSSES_DEFEATED as its Progress Stat,
# with a Stat Range of 0 to 10.
const BOSS_ACHIEVEMENT: String = "ACH_DEFEAT_10_BOSSES"
const BOSS_STAT: String = "STAT_BOSSES_DEFEATED"
const BOSS_TARGET: int = 10
func boss_defeated() -> void:
if not steam_ready:
return
var count: int = Steam.getStatInt(BOSS_STAT) + 1
Steam.setStatInt(BOSS_STAT, count)
if count >= BOSS_TARGET:
Steam.setAchievement(BOSS_ACHIEVEMENT)
elif count * 2 == BOSS_TARGET:
# Halfway: show the progress pop-up. This call does not change the stat.
Steam.indicateAchievementProgress(BOSS_ACHIEVEMENT, count, BOSS_TARGET)
Steam.storeStats()Sources: Steamworks documentation, ISteamUserStats (IndicateAchievementProgress), Stats and Achievements and Step by Step: Achievements; GodotSteam documentation, User Stats class.
How do I read global stats and global achievement percentages?
Request them, wait for the signal, then read. For totals over all players, mark the stat as Aggregated in Steamworks, call requestGlobalStats() with the number of history days (the limit is 60), and read getGlobalStatInt() or getGlobalStatFloat() after the global_stats_received signal.
For the share of players who have each achievement, call requestGlobalAchievementPercentages(). After the global_achievement_percentages_ready signal, getAchievementAchievedPercent() returns a dictionary with ret and percent, from 0 to 100. GodotSteam notes that this function may not return actual data until the game is released on Steam.
Valve warns that aggregated stats are in the hands of users and can be manipulated. Set Min Value, Max Value, Max Change and Increment Only on a stat that you aggregate.
GDScript
# In steamworks.gd. Connect the two signals once, in _ready(), after Steam starts:
# Steam.global_stats_received.connect(_on_global_stats_received)
# Steam.global_achievement_percentages_ready.connect(_on_global_percentages_ready)
func request_global_data() -> void:
if not steam_ready:
return
Steam.requestGlobalStats(0) # 0 days of history; the limit is 60
Steam.requestGlobalAchievementPercentages()
func _on_global_stats_received(_game_id: int, result: int) -> void:
if result == Steam.RESULT_OK:
# Only for a stat that is marked Aggregated in Steamworks.
print("All players: ", Steam.getGlobalStatInt("STAT_BOSSES_DEFEATED"))
func _on_global_percentages_ready(_game_id: int, result: int) -> void:
if result != Steam.RESULT_OK:
return
var data: Dictionary = Steam.getAchievementAchievedPercent("ACH_FIRST_BOSS")
if data.get("ret", false):
print("Unlocked by %.1f%% of players" % data["percent"])Sources: GodotSteam documentation, User Stats class; GodotSteam source code, godotsteam.cpp; Steamworks documentation, Stats and Achievements (Global Stats).
Which GodotSteam signals should I listen to?
Two signals cover most games: user_stats_stored and user_achievement_stored. Both arrive after storeStats(), and after indicateAchievementProgress(). You only receive signals if run_callbacks() runs, in _process() or through embedded callbacks.
user_achievement_stored arrives one time for each unlocked achievement. When current_progress and max_progress are both zero, the achievement is fully unlocked. Other values mean a progress notification.
In user_stats_stored, check the result. Valve says that a result of k_EResultInvalidParam means the server rejected one or more stats, because they broke the limits or were out of date, and sent back its own values. In GodotSteam the constant is Steam.RESULT_INVALID_PARAM.
GodotSteam says that callbacks can fail when run_callbacks() is in a node that can be paused. So the autoload in this guide sets its process mode to always.
| Signal | Arguments | Sent after |
|---|---|---|
| user_stats_stored | game_id, result | storeStats(), indicateAchievementProgress() |
| user_achievement_stored | game_id, group_achieve (unused), achievement_name, current_progress, max_progress | storeStats() with a new unlock, indicateAchievementProgress() |
| user_stats_received | game_id, result, user_id | requestUserStats() for another player |
| global_stats_received | game_id, result | requestGlobalStats() |
| global_achievement_percentages_ready | game_id, result | requestGlobalAchievementPercentages() |
| current_stats_received | Removed in GodotSteam 4.12 | It was the answer to requestCurrentStats() |
GDScript
# In steamworks.gd. Call this once from _ready(), after steam_ready is true.
func connect_steam_signals() -> void:
Steam.user_stats_stored.connect(_on_user_stats_stored)
Steam.user_achievement_stored.connect(_on_user_achievement_stored)
func _on_user_stats_stored(_game_id: int, result: int) -> void:
if result != Steam.RESULT_OK:
# RESULT_INVALID_PARAM: Steam rejected one or more stats and sent back its values.
push_warning("Steam did not store the stats, result %s" % result)
func _on_user_achievement_stored(_game_id: int, _group_achieve: bool, achievement_name: String, current_progress: int, max_progress: int) -> void:
if current_progress == 0 and max_progress == 0:
print("Unlocked on Steam: %s" % achievement_name)
else:
print("Progress on %s: %s of %s" % [achievement_name, current_progress, max_progress])Sources: GodotSteam documentation, User Stats class (Signals) and Initializing Steam tutorial; GodotSteam source code, godotsteam.cpp; Steamworks documentation, ISteamUserStats (Callbacks, StoreStats).
How do I test and reset achievements during development?
Call Steam.resetAllStats(true) to reset all stats and all achievements of the current player, or clearAchievement() and then storeStats() for one achievement. resetAllStats() stores the change on its own. Valve says that these calls are for tests during development. After a reset, read your stats again and reset the state of your game.
Valve also documents two commands for the Steam client console, with no code in your game. Start Steam with steam.exe -console, then use achievement_clear with the app ID and the achievement name, or reset_all_stats with the app ID.
There is no global reset for all players. Valve suggests a stat with a name such as Version: compare it with a number in your build, and when they differ, call resetAllStats() and write the new number.
Valve's two pages differ on what you see before release. The Stats and Achievements page says that earned achievements do not show in the Steam Community or the library before release, so your game needs its own output. The achievements guide says that you can preview achievements on your own Steam achievements page, linked from the editor. For store problems, Valve points to the file logs\stats_log.txt in the Steam install folder.
GDScript and Steam console
# In steamworks.gd. Keep these out of release builds, or behind a debug menu.
func reset_everything() -> void:
# true: reset the achievements too. Steam stores the change for you.
if steam_ready and not Steam.resetAllStats(true):
push_warning("resetAllStats() failed")
func relock(achievement: String) -> void:
if steam_ready and Steam.clearAchievement(achievement):
Steam.storeStats()
# Or, with no code, in the Steam client console (start Steam with: steam.exe -console):
# achievement_clear <appid> <achievement name>
# reset_all_stats <appid>Sources: Steamworks documentation, Stats and Achievements (Resetting stats, Testing), Step by Step: Achievements and ISteamUserStats (StoreStats); GodotSteam documentation, User Stats class and Stats And Achievements tutorial.
Why does my Steam achievement not pop in Godot?
Most often the achievement is not published, or the game set it and did not store it. Check the return values first: a false from setAchievement() points to the API name or to publishing, and a false from steamInitEx() points to Steam or the app ID. The table lists the causes that Valve and GodotSteam document.
The overlay is a special case in Godot 4. GodotSteam says that the Steam overlay often does not work or flickers when you run the project from the Godot 4 editor. In that case the achievement is unlocked, but you do not see the notification. The exported game should show the overlay when it runs through the Steam client.
One line of the GodotSteam common issues page is older than the rest of the documentation: it tells you to call requestUserStats() if you passed false to steamInit(). The initialization tutorial says that this argument was removed, so that advice applies only to old versions.
| Cause | How to see it | Fix |
|---|---|---|
| The achievement or stat is not published | setAchievement() or setStatInt() returns false; getAchievement() returns ret false. | Publish the changes from the Publish tab in Edit Steamworks Settings. |
| The API name is wrong | The same false results, for one name only. | Copy the API Name from Steamworks. The display name does not work. |
| The game set it and did not store it | No notification. getAchievement() returns achieved true. | Call storeStats() after setAchievement(). |
| The Steam overlay does not work | The user_achievement_stored signal arrives, but there is no pop-up, usually in a run from the editor. | Test the exported build from the Steam client. GodotSteam also lists the Compatibility renderer and auto-initialization as things that work for some people. |
| Steam is not running | steamInitEx() returns status 2, or the log shows "ConnectToGlobalUser failed". | Start the Steam client and sign in before you start the game. |
| The app ID is missing or is not your app | Initialisation fails, or it works with app ID 480 and your API names do not exist. | Pass your own app ID to steamInitEx() or set it in the Project Settings. The account must have the app in its library. |
| The Steam API file or the GodotSteam library is missing | The game crashes at start, or the Steam identifier is not declared. | Ship steam_api64.dll or libsteam_api.so with the build. Use the export templates of your GodotSteam flavour. |
| No callbacks | The unlock works, but your signal handlers do not run. | Call Steam.run_callbacks() in _process() of a node that does not pause. |
Sources: GodotSteam documentation, Common Issues, Initializing Steam, Exporting and Shipping, User Stats class and Stats And Achievements tutorial; Steamworks documentation, ISteamUserStats and Steamworks API Overview.
What do Steam achievements and stats tell you, and what do they not?
They tell you what share of all owners reached a point, and they tell the player what they did. After release, Steam shows a page of global achievement statistics for your game: the percentage of players who have each achievement, from the most common to the rarest. Valve calls it a resource for the developer: are your special challenges hard enough, or too hard?
That page is public, for your game and for every other game. Progress achievements in order (chapter 1, chapter 2, the end) give a rough completion funnel with no extra code.
They do not tell you who the players are or when they played. A global percentage is one number for all players and all time. It has no split by traffic source, by cohort, by build or by country, no session length, and no step between two achievements. Stats are written by the game client, and Valve says that this data can be manipulated. Achievements also answer only the questions that you made into achievements before launch.
So use achievements for players first. Use them as a free signal second, and do not make them your only measurement.
Sources: Steamworks documentation, Stats and Achievements (The Steam Community, Global Stats).
How do I add analytics next to GodotSteam in a Godot game?
Send an event at the moment of the unlock. The Manalens Godot addon is plain GDScript and runs next to GodotSteam in the same project. Its track() function takes a snake_case event name and a dictionary of flat properties, so one line records which achievement a player unlocked, in which session and in which build.
achievement_unlocked is a custom event name in this example. It is not one of the events that the SDK sends on its own, and it is not in the standard event conventions. The standard events are level_start, level_complete and level_fail, and the SDK sends game_open and session_start for you.
With the events in place, a funnel shows the drop between two steps, retention shows who returns, and the App filters compare one build with the next. If players come from your website, install attribution links the first launch to a website visit. Steam achievements stay what the player sees; the events are what you read.
- How to add analytics to a Godot game →
- Best analytics tools for Godot games in 2026 →
- What events to track first in your game →
- Funnels →
- Retention →
GDScript
# In steamworks.gd, with the Manalens addon enabled.
func unlock_and_track(achievement: String) -> void:
var is_new: bool = not is_unlocked(achievement)
unlock(achievement)
if is_new:
# A custom event. The name and the property are your choice.
Manalens.track("achievement_unlocked", {"achievement": achievement})Sources: Manalens Godot SDK and app events documentation.
How do I start?
Manalens is the analytics and growth engine built for games. Add GodotSteam for achievements, add the Godot addon for events, and read both: Steam for the global percentages, the Game KPIs board for retention, sessions and level results by build.
Sources: Manalens Godot SDK documentation.
Frequently asked questions
Do I still need requestCurrentStats() in GodotSteam?
No, not on a current version. Valve marks RequestCurrentStats as deprecated, because the Steam client loads stats and achievements before launch. The GodotSteam changelog removed the current_stats_received callback in version 4.12, and the tutorial says that 4.14 and newer need nothing extra. On GodotSteam 4.24 you call getAchievement() and getStatInt() directly after steamInitEx().
Why does setAchievement() return false in GodotSteam?
Because Steam does not know the API name. GodotSteam and Valve give two causes: the achievement does not exist in the Steamworks settings of the app, or the changes are not published. Also check that the game started with your own app ID and not with 480, and that steamInitEx() returned status 0.
Does GodotSteam work with C#?
Not directly. The GodotSteam documentation says that there is no .NET version of GodotSteam yet. Its C# tutorial points to community C# bindings for the GDExtension version, and to Steamworks.NET and Facepunch.Steamworks as separate C# libraries. This guide uses GDScript only, and we did not test the C# routes.
Can I test Steam achievements before my game is released?
Yes. GodotSteam says that the game does not need to be released or approved, but you must publish the achievement and stat changes in Steamworks. Run the game with your own app ID and the Steam client open. Reset with resetAllStats(true), or with the reset_all_stats console command that Valve documents.
How often can I call storeStats()?
Not often. Valve says that the call can be rate limited and that the frequency should be on the order of minutes, not seconds: the end of a round, a map change or a checkpoint. The exception is an unlock. Call storeStats() soon after setAchievement(), because the call is required to show the notification.
Sources and implementation
- GodotSteam documentation: Tutorials, Stats And Achievements (last updated 19 February 2026, read 19 November 2026) ↗
- GodotSteam documentation: User Stats class (read 19 November 2026) ↗
- GodotSteam documentation: Tutorials, Initializing Steam (last updated 14 May 2026, read 19 November 2026) ↗
- GodotSteam documentation: Main class (read 19 November 2026) ↗
- GodotSteam documentation: Getting Started (read 19 November 2026) ↗
- GodotSteam documentation: What Are You Actually Making? (read 19 November 2026) ↗
- GodotSteam documentation: Compiling The GodotSteam GDExtension From Scratch (read 19 November 2026) ↗
- GodotSteam documentation: Tutorials, Exporting and Shipping (last updated 22 September 2025, read 19 November 2026) ↗
- GodotSteam documentation: Common Issues (read 19 November 2026) ↗
- GodotSteam documentation: Godot 4.x changelog (read 19 November 2026) ↗
- GodotSteam documentation: Tutorials, C-Sharp (last updated 27 January 2026, read 19 November 2026) ↗
- GodotSteam source code: godotsteam.cpp, godot4 branch (Codeberg, read 19 November 2026) ↗
- Steamworks documentation: Stats and Achievements (Valve, read 19 November 2026) ↗
- Steamworks documentation: Step by Step: Achievements (Valve, read 19 November 2026) ↗
- Steamworks documentation: ISteamUserStats interface (Valve, read 19 November 2026) ↗
- Steamworks documentation: Steamworks API Overview (Valve, read 19 November 2026) ↗