Steamworks SDK
Integrate Valve's Steamworks SDK for achievements, leaderboards, Cloud saves, Workshop modding, multiplayer lobbies, DLC ownership checks, and SteamPipe depot builds on PC.
When to Use
Use this skill when the task involves any of the following Steamworks features:
- Achievements & stats: unlocking, incrementing, and storing per-user stats via
ISteamUserStats.
- Leaderboards: global/friend score tables, upload and download.
- Steam Cloud: cross-machine save sync via Remote Storage or Auto-Cloud.
- Workshop / UGC: publishing, subscribing to, and loading mods via
ISteamUGC.
- Lobbies & multiplayer: matchmaking lobbies, P2P, and Game Networking Sockets.
- DLC & ownership: gating content by
IsDlcInstalled / ownership queries.
- Rich presence, overlay, depots/builds via SteamPipe.
Do Not Use
| If the task is… |
Use instead |
| iOS/Android in-app purchases or store submission |
game-mobile-store-integration |
| Web/server payments, subscriptions |
stripe-integration |
| Console (Switch/PS/Xbox) cert & online |
game-console-porting-certification |
| Godot networking high-level API only |
game-godot-multiplayer-networking |
Prerequisites
- A Steam App ID issued by Valve (requires a paid Steam Direct app).
- The Steamworks SDK downloaded from the partner site and linked into the project (headers +
steam_api64.lib / steam_api64.dll on Windows).
- The Steam client running and logged in for local development testing.
- Achievements, stats, and leaderboards defined on the Steamworks partner site before the API can reference them.
steamcmd installed for SteamPipe build uploads (download from Valve's SteamPipe docs).
Procedure
1. Setup Contract
- Obtain an App ID from Valve (paid Steam Direct app).
- Place
steam_appid.txt (containing only the App ID as plain text) next to the executable for development only — never ship it; the launched-from-Steam client provides the App ID in production.
- Call
SteamAPI_Init() early in startup; if it fails, the game was not launched through Steam (or steam_appid.txt / running client is missing) — handle gracefully.
- Call
SteamAPI_RunCallbacks() every frame, and SteamAPI_Shutdown() on exit.
if (!SteamAPI_Init()) {
// Not launched via Steam, or Steam client not running.
// Fail soft: disable Steam features, don't crash.
}
// per frame:
SteamAPI_RunCallbacks(); // REQUIRED — without it, no callbacks fire
// on exit:
SteamAPI_Shutdown();
Hard rule: steam_appid.txt must be excluded from all shipping/release builds. Shipping it lets the game run without ownership checks.
2. Achievements & Stats
// SDK 1.61+ requests the current user's stats automatically at startup
// (RequestCurrentStats was removed). On older SDKs, call
// SteamUserStats()->RequestCurrentStats() and wait for UserStatsReceived.
// Unlock + push to server (StoreStats is what actually persists/displays).
SteamUserStats()->SetAchievement("ACH_FIRST_BLOOD");
SteamUserStats()->SetStat("enemies_killed", killCount);
SteamUserStats()->StoreStats(); // batch then store once, not per-kill
Steps:
- Define every achievement and stat on the Steamworks partner site first; the API only references IDs that already exist there. Undefined IDs cause silent no-ops.
- Batch
SetStat / SetAchievement calls, then call StoreStats() once — calling StoreStats() per event is rate-limited and slow.
- For testing, use
ClearAchievement() and ResetAllStats(true) to reset progress.
3. Leaderboards
// Find-or-create, then upload. Both are async (SteamCall + callback).
SteamAPICall_t h = SteamUserStats()->FindOrCreateLeaderboard(
"HighScores", k_ELeaderboardSortMethodDescending,
k_ELeaderboardDisplayTypeNumeric);
// in the callback, with the handle:
SteamUserStats()->UploadLeaderboardScore(
leaderboard, k_ELeaderboardUploadScoreMethodKeepBest, score, nullptr, 0);
- Use
KeepBest for high-score tables.
- Use
ForceUpdate only when the latest value must always win (e.g. fastest current time where lower is better but semantics differ from a simple max).
4. Steam Cloud Saves
- Simplest path: enable Auto-Cloud in the partner site (map file globs to Cloud) — zero code, but no conflict logic.
- Code path: use
ISteamRemoteStorage::FileWrite / FileRead with a quota check.
- Hard rule: handle the sync conflict case (two machines, newer save) explicitly; never blind-overwrite. Blind overwrites lose progress on multi-PC users.
- Keep saves small and versioned; Cloud has per-user quota.
5. Workshop (UGC)
// Create an item, then update its content/preview, then submit.
SteamAPICall_t c = SteamUGC()->CreateItem(appId, k_EWorkshopFileTypeCommunity);
// in callback (PublishedFileId_t id):
UGCUpdateHandle_t u = SteamUGC()->StartItemUpdate(appId, id);
SteamUGC()->SetItemContent(u, "C:/mod/content");
SteamUGC()->SetItemPreview(u, "C:/mod/preview.png");
SteamUGC()->SubmitItemUpdate(u, "initial version");
For consuming mods:
- Call
GetSubscribedItems to enumerate subscribed items.
- Call
GetItemInstallInfo to get the local folder path.
- Load mod content from disk.
- Never assume a mod folder exists; users unsubscribe mid-session. Always check validity before loading.
6. Lobbies & Networking
- Matchmaking lobbies (
ISteamMatchmaking::CreateLobby, RequestLobbyList, lobby data key/values) for grouping players and exchanging connection metadata.
- For transport, prefer Steam Game Networking Sockets (
ISteamNetworkingSockets) over the legacy P2P API — it provides NAT punch-through, relays (SDR), and encryption.
- Lobby data is the meeting point; actual gameplay traffic goes over the sockets connection negotiated via the lobby.
Hard rule: do not use the legacy P2P API for new projects. Use Game Networking Sockets for NAT traversal + encryption.
7. DLC & Ownership
- Gate DLC content with
SteamApps()->IsDlcInstalled(dlcAppId).
- Centralize the App ID; mismatches break ownership and stats queries.
8. SteamPipe Builds
| Concept |
Meaning |
| Depot |
A bucket of files (e.g. per-OS, per-DLC) |
| App build |
A set of depot snapshots published to a branch |
| Branch |
default (live) or beta branches (password-gated) |
Upload via steamcmd + a app_build_*.vdf script (or the Web/Steamworks UI).
Hard rule: always publish to a beta branch first, validate, then promote to default.
Example PowerShell command to upload a build:
steamcmd +login <build_account> +run_app_build /path/to/app_build_480.vdf +quit
Replace <build_account> with your Steamworks build account (never hardcode live credentials in scripts).
Pitfalls
- Shipping
steam_appid.txt: lets the game run without ownership checks — remove it from release builds.
- Never calling
RunCallbacks(): every async result (stats, leaderboards, UGC) silently never returns.
StoreStats() per event: rate-limited and slow. Batch SetStat/SetAchievement, then StoreStats() once.
- Using achievements that aren't defined on the partner site: API calls no-op silently.
- Blind Cloud overwrite: loses progress on multi-PC users. Implement conflict handling.
- Assuming Steam is always present:
SteamAPI_Init can fail (offline, no client). Degrade gracefully, never hard-crash.
- Legacy P2P for new projects: use Game Networking Sockets for NAT traversal + encryption.
- Hardcoding the App ID in many places: centralize it; mismatches break ownership/stats.
Verification
Related Skills
game-mobile-store-integration — the mobile-store equivalent (IAP, store services).
game-console-porting-certification — console online/cert when porting beyond PC.
game-godot-multiplayer-networking / game-unreal-engine — engine-side networking these lobbies feed into.
References
- Steamworks SDK documentation: Stats & Achievements, Leaderboards, Remote Storage, UGC, Matchmaking, Game Networking Sockets, SteamPipe — available on the Steamworks partner site.
- Load
references/ files when deeper API surface detail is needed (e.g. callback structures, VDF schema examples). Check the references/ directory for supplementary docs before writing complex integration code.
1---
2name: game-steamworks-sdk
3version: 1.1.2
4description: "Use when integrating the Steamworks SDK into a PC game — Steam achievements and stats, leaderboards, Steam Cloud saves, Workshop (UGC) modding, matchmaking lobbies and P2P, rich presence, DLC ownership checks, and depot/build uploads via SteamPipe. Triggers on Steamworks, ISteamUserStats, ISteamRemoteStorage, ISteamUGC, ISteamMatchmaking, app_id, steam_appid.txt, SteamPipe, achievements, leaderboards, Workshop. Not for mobile App Store/Play IAP (use game-mobile-store-integration), Stripe/web payments (use stripe-integration), or console certification (use game-console-porting-certification)."
5risk: safe
6source: opus
7date_added: 2026-06-27
8metadata:
9 source: https://skillmd.com/skills/kayforkind/game-steamworks-sdk
10---
11
12# Steamworks SDK
13
14Integrate Valve's Steamworks SDK for achievements, leaderboards, Cloud saves, Workshop modding, multiplayer lobbies, DLC ownership checks, and SteamPipe depot builds on PC.
15
16## When to Use
17
18Use this skill when the task involves any of the following Steamworks features:
19
20- **Achievements & stats**: unlocking, incrementing, and storing per-user stats via `ISteamUserStats`.
21- **Leaderboards**: global/friend score tables, upload and download.
22- **Steam Cloud**: cross-machine save sync via Remote Storage or Auto-Cloud.
23- **Workshop / UGC**: publishing, subscribing to, and loading mods via `ISteamUGC`.
24- **Lobbies & multiplayer**: matchmaking lobbies, P2P, and Game Networking Sockets.
25- **DLC & ownership**: gating content by `IsDlcInstalled` / ownership queries.
26- **Rich presence, overlay, depots/builds** via SteamPipe.
27
28### Do Not Use
29
30| If the task is… | Use instead |
31|---|---|
32| iOS/Android in-app purchases or store submission | `game-mobile-store-integration` |
33| Web/server payments, subscriptions | `stripe-integration` |
34| Console (Switch/PS/Xbox) cert & online | `game-console-porting-certification` |
35| Godot networking high-level API only | `game-godot-multiplayer-networking` |
36
37## Prerequisites
38
391. A **Steam App ID** issued by Valve (requires a paid Steam Direct app).
402. The **Steamworks SDK** downloaded from the partner site and linked into the project (headers + `steam_api64.lib` / `steam_api64.dll` on Windows).
413. The **Steam client** running and logged in for local development testing.
424. Achievements, stats, and leaderboards **defined on the Steamworks partner site** before the API can reference them.
435. `steamcmd` installed for SteamPipe build uploads (download from Valve's SteamPipe docs).
44
45## Procedure
46
47### 1. Setup Contract
48
491. Obtain an **App ID** from Valve (paid Steam Direct app).
502. Place `steam_appid.txt` (containing only the App ID as plain text) next to the executable **for development only** — never ship it; the launched-from-Steam client provides the App ID in production.
513. Call `SteamAPI_Init()` early in startup; if it fails, the game was not launched through Steam (or `steam_appid.txt` / running client is missing) — handle gracefully.
524. Call `SteamAPI_RunCallbacks()` **every frame**, and `SteamAPI_Shutdown()` on exit.
53
54```cpp
55if (!SteamAPI_Init()) {
56 // Not launched via Steam, or Steam client not running.
57 // Fail soft: disable Steam features, don't crash.
58}
59// per frame:
60SteamAPI_RunCallbacks(); // REQUIRED — without it, no callbacks fire
61// on exit:
62SteamAPI_Shutdown();
63```
64
65**Hard rule**: `steam_appid.txt` must be excluded from all shipping/release builds. Shipping it lets the game run without ownership checks.
66
67### 2. Achievements & Stats
68
69```cpp
70// SDK 1.61+ requests the current user's stats automatically at startup
71// (RequestCurrentStats was removed). On older SDKs, call
72// SteamUserStats()->RequestCurrentStats() and wait for UserStatsReceived.
73
74// Unlock + push to server (StoreStats is what actually persists/displays).
75SteamUserStats()->SetAchievement("ACH_FIRST_BLOOD");
76SteamUserStats()->SetStat("enemies_killed", killCount);
77SteamUserStats()->StoreStats(); // batch then store once, not per-kill
78```
79
80Steps:
811. Define every achievement and stat on the **Steamworks partner site first**; the API only references IDs that already exist there. Undefined IDs cause silent no-ops.
822. Batch `SetStat` / `SetAchievement` calls, then call `StoreStats()` once — calling `StoreStats()` per event is rate-limited and slow.
833. For testing, use `ClearAchievement()` and `ResetAllStats(true)` to reset progress.
84
85### 3. Leaderboards
86
87```cpp
88// Find-or-create, then upload. Both are async (SteamCall + callback).
89SteamAPICall_t h = SteamUserStats()->FindOrCreateLeaderboard(
90 "HighScores", k_ELeaderboardSortMethodDescending,
91 k_ELeaderboardDisplayTypeNumeric);
92// in the callback, with the handle:
93SteamUserStats()->UploadLeaderboardScore(
94 leaderboard, k_ELeaderboardUploadScoreMethodKeepBest, score, nullptr, 0);
95```
96
97- Use `KeepBest` for high-score tables.
98- Use `ForceUpdate` only when the latest value must always win (e.g. fastest current time where lower is better but semantics differ from a simple max).
99
100### 4. Steam Cloud Saves
101
102- **Simplest path**: enable **Auto-Cloud** in the partner site (map file globs to Cloud) — zero code, but no conflict logic.
103- **Code path**: use `ISteamRemoteStorage::FileWrite` / `FileRead` with a quota check.
104- **Hard rule**: handle the **sync conflict** case (two machines, newer save) explicitly; never blind-overwrite. Blind overwrites lose progress on multi-PC users.
105- Keep saves small and versioned; Cloud has per-user quota.
106
107### 5. Workshop (UGC)
108
109```cpp
110// Create an item, then update its content/preview, then submit.
111SteamAPICall_t c = SteamUGC()->CreateItem(appId, k_EWorkshopFileTypeCommunity);
112// in callback (PublishedFileId_t id):
113UGCUpdateHandle_t u = SteamUGC()->StartItemUpdate(appId, id);
114SteamUGC()->SetItemContent(u, "C:/mod/content");
115SteamUGC()->SetItemPreview(u, "C:/mod/preview.png");
116SteamUGC()->SubmitItemUpdate(u, "initial version");
117```
118
119For consuming mods:
1201. Call `GetSubscribedItems` to enumerate subscribed items.
1212. Call `GetItemInstallInfo` to get the local folder path.
1223. Load mod content from disk.
1234. **Never assume a mod folder exists**; users unsubscribe mid-session. Always check validity before loading.
124
125### 6. Lobbies & Networking
126
127- **Matchmaking lobbies** (`ISteamMatchmaking::CreateLobby`, `RequestLobbyList`, lobby data key/values) for grouping players and exchanging connection metadata.
128- For transport, prefer **Steam Game Networking Sockets** (`ISteamNetworkingSockets`) over the legacy P2P API — it provides NAT punch-through, relays (SDR), and encryption.
129- Lobby data is the meeting point; actual gameplay traffic goes over the sockets connection negotiated via the lobby.
130
131**Hard rule**: do not use the legacy P2P API for new projects. Use Game Networking Sockets for NAT traversal + encryption.
132
133### 7. DLC & Ownership
134
135- Gate DLC content with `SteamApps()->IsDlcInstalled(dlcAppId)`.
136- Centralize the App ID; mismatches break ownership and stats queries.
137
138### 8. SteamPipe Builds
139
140| Concept | Meaning |
141|---|---|
142| **Depot** | A bucket of files (e.g. per-OS, per-DLC) |
143| **App build** | A set of depot snapshots published to a branch |
144| **Branch** | `default` (live) or beta branches (password-gated) |
145
146Upload via `steamcmd` + a `app_build_*.vdf` script (or the Web/Steamworks UI).
147
148**Hard rule**: always publish to a **beta branch first**, validate, then promote to `default`.
149
150Example PowerShell command to upload a build:
151
152```powershell
153steamcmd +login <build_account> +run_app_build /path/to/app_build_480.vdf +quit
154```
155
156Replace `<build_account>` with your Steamworks build account (never hardcode live credentials in scripts).
157
158## Pitfalls
159
1601. **Shipping `steam_appid.txt`**: lets the game run without ownership checks — remove it from release builds.
1612. **Never calling `RunCallbacks()`**: every async result (stats, leaderboards, UGC) silently never returns.
1623. **`StoreStats()` per event**: rate-limited and slow. Batch `SetStat`/`SetAchievement`, then `StoreStats()` once.
1634. **Using achievements that aren't defined on the partner site**: API calls no-op silently.
1645. **Blind Cloud overwrite**: loses progress on multi-PC users. Implement conflict handling.
1656. **Assuming Steam is always present**: `SteamAPI_Init` can fail (offline, no client). Degrade gracefully, never hard-crash.
1667. **Legacy P2P for new projects**: use Game Networking Sockets for NAT traversal + encryption.
1678. **Hardcoding the App ID in many places**: centralize it; mismatches break ownership/stats.
168
169## Verification
170
171- [ ] `SteamAPI_Init` failure is handled (game still launches, features disabled).
172- [ ] `SteamAPI_RunCallbacks()` runs every frame; `SteamAPI_Shutdown()` on exit.
173- [ ] `steam_appid.txt` is excluded from shipping builds.
174- [ ] Achievements/stats exist on the partner site; stats batched then `StoreStats()`.
175- [ ] Leaderboard upload uses the correct method (`KeepBest` vs `ForceUpdate`).
176- [ ] Cloud sync handles the multi-machine conflict case.
177- [ ] Workshop consumption tolerates missing/unsubscribed items.
178- [ ] Builds publish to a beta branch and are validated before promotion to `default`.
179
180## Related Skills
181
182- `game-mobile-store-integration` — the mobile-store equivalent (IAP, store services).
183- `game-console-porting-certification` — console online/cert when porting beyond PC.
184- `game-godot-multiplayer-networking` / `game-unreal-engine` — engine-side networking these lobbies feed into.
185
186## References
187
188- **Steamworks SDK documentation**: Stats & Achievements, Leaderboards, Remote Storage, UGC, Matchmaking, Game Networking Sockets, SteamPipe — available on the Steamworks partner site.
189- Load `references/` files when deeper API surface detail is needed (e.g. callback structures, VDF schema examples). Check the `references/` directory for supplementary docs before writing complex integration code.