Cachievementmgr: Failed to Upload Stats to Steam

Overview

Steam Stats and Achievements provides an easy way for your game to provide persistent, roaming accomplishment and statistics tracking for your users. The user's data is associated with their Steam business relationship, and each user's achievements and statistics can be formatted and displayed in their Steam Community Contour.

What they are good for

In addition to providing highly-valued rewards to players of your games, achievements are useful for encouraging and rewarding teamwork and role player interaction, providing extra dimensionality to the game objectives, and rewarding users for spending more of their time in-game.

Statistics rails fine-grained pieces of data, such as playtime, number of ability-ups used, etc. You may cull to use them only for tracking internal game data - so that, for instance, yous can grant an achievement based on multi-session game play statistics collected from the user across multiple computers.

Implementation Overview

Ascertain Your Game's Stats and Achievements

Achievements are application specific and are setup on the App Admin page of the Steamworks partner site.

There are 3 types of statistics your game can store:

INT - A 32-scrap (signed) integer (due east.g. number of games played)
Bladder - A 32-bit floating bespeak value (e.g. number of miles driven)
AVGRATE - A moving average. Encounter: The AVGRATE stat type

The Steamworks Partner Website provides an interface for defining and updating your game's statistics and achievements. Using it, you can:

Ascertain the initial statistics and achievements
Add together additional stats and achievements
Update achievement names, descriptions, and icons
Update statistic parameters and constraints (max/min values, moving-boilerplate window sizes, etc)

Stats have the post-obit backdrop:

ID - An automatically-generated numerical ID for each stat.
Type - The type of this Stat - INT, Bladder, or AVGRATE.
API Name - The string used to access this stat using the API.
Set By - Sets who can modify the stat. The default is Client. For more than see Game Server Stats.
Increment Only - If set up, this stat is just allowed to increase in value over time.
Max Alter - If set, sets a limit on the amount that the stat's value can change from ane SetStat call to the next.
Min Value - If set, the minimum numerical value this stat may take. By default, the min is the minimum of the underlying numerical type (INT_MIN or -FLT_MAX).
Max Value - If set, the maximum numerical value this stat may take. By default, the max is the maximum of the underlying numerical type (INT_MAX or FLT_MAX).
Default Value - If gear up, the default value that this stat will initially be set to for a new user. If not prepare, the default value is zero.
Aggregated - If set, Steam will keep a global full for this stat. See Global Stats beneath for more than information.
Display Proper name - The name of this stat, when displayed in your app.

AVGRATE stats have the following boosted backdrop:

Window - The size of the "sliding window" used to average your information.

An AVGRATE stat is 1 that is automatically averaged by Steam. See the AVGRATE department below for more than information.

Achievements have the following properties:

ID - An automatically-generated numerical ID for each achievement.
API Name - The cord used to admission this achievement using the API.
Progress Stat - Specifies a stat that'southward used as a progress bar in the Community for this achievement. The achievement will also automatically unlock when the stat reaches the unlock value.
Display Name - The name this achievement will take in client notification popular-ups, and in the Community. May be localized.
Description - A description of this accomplishment, for displaying in the Community. May be localized.
Set By - Sets who can unlock the accomplishment. The default is customer. For more see Game Server Stats.
Hidden? - If true, a "hidden" achievement does not show upwardly on a user'south Community folio (at all) until they have achieved information technology.
Accomplished Icon - The icon to display when it is achieved.
Unachieved Icon - The icon to display when it is not yet achieved.

The post-obit is the list of achievements from the Steamworks API Instance Application (SpaceWar):

Special Considerations

Achievement names and icons should be all-ages appropriate.
By default, games are express to 100 achievements at beginning. Accomplish out to usa via the "Support" option at the top of this page if you take questions most this.

How to utilise them

Accessing Stats and Achievements from inside your game:

After initializing the Steamworks API you can start to use the Stats and Achievements API which is contained within ISteamUserStats.
At the start of a game session, call ISteamUserStats::RequestCurrentStats to fetch the user's stats and achievement information from the Steam back end. You lot will receive a ISteamUserStats::UserStatsReceived_t callback when the data is ready.
Use ISteamUserStats::GetStat and ISteamUserStats::GetAchievement to iterate the data and initialize game country.
If you want to display the achievements in your game you tin can use ISteamUserStats::GetAchievementDisplayAttribute to retrieve human-readable properties of the accomplishment, including its proper noun ("proper name") and description ("desc"). These properties are localizable on the Steamworks Partner Website, and the returned data varies with the language in which the user is running the game. You can as well get an achievement's icon using ISteamUserStats::GetAchievementIcon or the fourth dimension each achievements was unlocked with ISteamUserStats::GetAchievementAndUnlockTime.
Whenever a stat changes, peculiarly before whatever changes are shown to the user, call ISteamUserStats::SetStat or ISteamUserStats::UpdateAvgRateStat. These calls only alter Steam's in-memory state and are very inexpensive. Doing then allows Steam to persist the changes between sessions fifty-fifty in outcome of game crash.
At appropriate points within your game (i.east. checkpoints, level transitions), phone call ISteamUserStats::StoreStats to upload the changes. Y'all volition receive a ISteamUserStats::UserStatsStored_t callback when that has completed.
For achievements that accept progress bars use ISteamUserStats::IndicateAchievementProgress at meaning points to show a pop-upward with the progress. For example, if you need 20 wins you may want to call this at 10 wins to show that the user has made it halfway.
Whenever one or more achievements are unlocked, call ISteamUserStats::SetAchievement for each unlocked achievement and so ISteamUserStats::StoreStats to immediately upload them. Your game will meet a ISteamUserStats::UserStatsStored_t callback, plus one ISteamUserStats::UserAchievementStored_t callback for each unlocked achievement. The Steam Game Overlay will display a notification console to the user.

The AVGRATE stat type

This type of stat provides some unique and very useful functionality, but it requires a little bit more detail to explain.

Consider the case where y'all'd similar to track an average statistic, such as "Points earned per hour". I approach would be to have ii stats, an INT "TotalPoints" and a Float "TotalPlayTimeHours", and and so split points by time to get Points per Hour.

The downside to this implementation is that, once the player has accumulated a significant amount of playtime, the calculated average will modify extremely slowly. In fact, the more than the user plays the game, the less responsive that average volition exist. If the user has spent 100 hours playing the game, the calculated average will "lag" by about 50 hours of that. If they increase their skill, they will not run into the increase in Points Per 60 minutes that they expect.

The AVGRATE stat type lets you lot implement a "sliding window" effect on the average. For example, you tin utilize only the previous few hours of gameplay, and so the statistic will more than accurately reverberate the actor's current skill level.

Let's set up an AVGRATE stat to implement "points per 60 minutes" where only the previous xx hours of gameplay bear on the value. To exercise this, you would:

Note that, because the average will be "per hour", the time units on all time parameters associated with this stat will exist "hours". This applies to the Window holding on the stat itself, and also for the "dSessionLength" parameter passed in to UpdateAvgRateStat below.
Create an AVGRATE stat named "AvgPointsPerHour", and a Window property of xx.0 (remember, that's in "hours")
At appropriate points during your game, telephone call ISteamUserStats::UpdateAvgRateStat with the following parameters:
- pchName - "AvgPointsPerHour"
- flCountThisSession - The number of points the player earned since the last call to UpdateAvgRateStat.
- dSessionLength - The amount of game time since the concluding call to UpdateAvgRateStat. The unit of measurement should be the same as the unit of measurement on the stat's Window property. In this example, it is "hours".
For instance, if the player earned 77 points in the last round, which lasted 0.225 hours (13.5 minutes), that would be SteamUserStats()->UpdateAvgRateStat( "AvgPointsPerHour", 77, 0.225 )

In the higher up instance, Steam will have the current rounds boilerplate of 342.two points per 60 minutes ( 77 divided past 0.225 ) and blend it with the previous value. The result will reflect the total boilerplate over the player's last 20 hours of game time. If this were the first fourth dimension the stat was updated for the current user, the electric current value would be 342.two.

This instance uses "hours" as the time unit of measurement, just y'all may utilize whatever time unit you wish. Just keep in heed that you must consistently utilise that unit as your base for "dSessionLength", too every bit the Window property.

Getting stats for other users

You can use ISteamUserStats::RequestUserStats to become the stats for another user. You tin then use ISteamUserStats::GetUserStat, ISteamUserStats::GetUserAchievement, and ISteamUserStats::GetUserAchievementAndUnlockTime to go data for that user. This data is not updated automatically every bit the other user uploads new stats, and then to refresh the information only telephone call ISteamUserStats::RequestUserStats again.

To keep from using too much memory, a Least Recently Used (LRU) cache is maintained and other user'south stats will occasionally exist unloaded. When this happens a ISteamUserStats::UserStatsUnloaded_t callback is automatically sent. When this callback is sent then the specified user's stats volition exist unavailable until ISteamUserStats::RequestUserStats is called again.

Offline fashion

Steam keeps a local cache of the stats and achievement information so that the APIs tin exist used every bit normal in offline mode. Any stats unable to be committed are saved for the next time the user is online. In the event that there have been modifications on more than 1 machine, Steam volition automatically merge achievements and choose the set of stats that has had more progress. Because Steam keeps a local cache of stats data it is not necessary for the game to also go on a local cache of the data on disk. Such caches often come up in conflict, and when they do it looks to users as if their progress has been reverted, which is a frustrating experience.

Game Server Stats

Parallel to ISteamUserStats is ISteamGameServerStats for game servers. These can get stats for users in the same way equally clients tin (described above). They can too set stats and honor achievements, but only if "Set by" is set to GS (game server) or Official GS. The departure betwixt game servers and official game servers is that official game servers are servers that you host and control. Using official game servers to set stats offers enhanced security confronting cheating, as users may exist able to modify their own game servers or spoof being a game server. To define official game servers, enter the IP ranges of the servers here.

Stats and achievements that are settable by game servers cannot exist gear up past clients. Game servers tin only set stats and achievements for users currently playing on the server. If the user leaves the server there is a brusque grace menses to gear up any final stats, just then whatever new uploads will be denied. This is to assistance ensure consistency and to avoid making it possible for a malicious game server to set anyone'south stats at any time. Given the restriction, it is of import not to wait until the stop of a round to set stats. Ready them continuously so you can store them as a user quits.

Clients will get automatic updates when a game server changes their stats. Withal, similar clients, stats loaded past the server for other users are not refreshed automatically and tin can historic period out.

Resetting stats

During development, it is often the instance that a consummate wipe of stats and achievements on an business relationship or all accounts is desirable for testing. To wipe stats for an account, call ISteamUserStats::ResetAllStats with bAchievementsToo fix to true to wipe achievements as well. Once chosen recollect to reiterate your stats and achievements and reset your in-memory game country. There is no style to globally wipe stats and achievements for all users. One of the reasons for this is that even if a global wipe were to be done, games in-progress may not find the wipe and write back in-retentiveness values. Fortunately, there is an easy way to build a global wipe organization into your game. To do then:

Ascertain a stat with a proper noun like "Version"
Put a hardcoded stats version number in the game
Once stats take been loaded, compare the "Version" stat confronting your hardcoded version number
If they don't match, phone call ISteamUserStats::ResetAllStats and and so gear up the "Version" stat to the hardcoded number.

This style, whenever you lot want a global wipe but modify the hardcoded stats version number. The global wipe will then happen every bit people get the new build.

Stat consistency

It'southward a best practice to call up about how related stats could become inconsistent. For example, you lot may have iii stats "GamesWon", "GamesLost", and "GamesPlayed". Despite the best of intentions, stats can and do go out of sync with each other. In this instance, that could atomic number 82 to games won and lost not calculation up to the total of games played. If this was resolved by removing the "GamesLost" stat and instead computing information technology as "GamesPlayed" - "GamesWon", an inconsistency could cause "GamesLost" to be negative. In this case, information technology'southward best to drop the "GamesPlayed" stat and compute it equally "GamesWon" + "GamesLost".

Global Stats

Stats can be marked as aggregated on the admin page to tell Steam to go on a global full of all users' values for the stat. This can be used to get information on total money in the economic system, full kills, favorite weapons, favorite maps, and which team tends to do better. On the flip side, this should not be used for stats like "MostKills" as adding that up for multiple users would be meaningless. As stats are in the hands of users, this data is field of study to being manipulated. Therefore it'southward crucial when using aggregated stats to set skillful bounds for min value, max value, increment only (if appropriate), and max change. Max change has a special meaning for aggregated stats. When a new value is uploaded, the global value will alter no more than the max change value. This limits how quickly a cheater tin can influence the global totals.

To access the global totals, call ISteamUserStats::RequestGlobalStats and then ISteamUserStats::GetGlobalStat for each global stat. You can as well enquire for ISteamUserStats::RequestGlobalStats for a specified number of days of history. The history is the amount that stat inverse every day. You lot tin access that history with ISteamUserStats::GetGlobalStatHistory.

You lot can also request global accomplishment completion percentages from the client. To practice so outset call ISteamUserStats::RequestGlobalAchievementPercentages. So, iterate the achievements in order of about completed to least completed past calling ISteamUserStats::GetMostAchievedAchievementInfo and ISteamUserStats::GetNextMostAchievedAchievementInfo. Y'all can also go the completion percentage for a item achievement by calling ISteamUserStats::GetAchievementAchievedPercent.

Testing

Earlier your app is released, you volition not exist able to run into which achievements have been earned in the Steam Community or library. Your app will need a way to output what achievements accept been earned for the user.

To clear an accomplishment or stats without adding lawmaking to your game, you lot can utilise the Steam client console. Run with steam.exe -console, then:

achievement_clear <appid> <accomplishment name>
reset_all_stats <appid>

The Steam Community

After your game has been released then data nigh private and global accomplishment progress volition be displayed in the Steam Community. Each player will accept a link from their Community profile that goes to a page showcasing what they accept achieved, and which they have withal to unlock.

NOTE: Your achievements will not be shown until your app is somewhat visible to the community.

Each achievement is listed with the appropriate icon, and the name and clarification equally set in the Steamworks control panel. If the achievement name and description have been localized into the linguistic communication the user has selected, then they will display in that linguistic communication.

There will likewise be a link from this page, and 1 from your game'south master Steam page, to a set of global achievement statistics for your game. It displays the percentage of Steam players of the game that take achieved each one, ordered from nearly common to the rarest achievement. This is fun for players to meet, and as well a corking resources for you as a programmer: are your special challenges hard plenty? Or maybe besides hard? (this information is also available on the Sales and Activations Reports site).