The Steamworks Stats companion plugin extends Construct’s official Steamworks plugin with access to the native Steamworks Stats and Achievements API ISteamUserStats. It is currently supported with the Windows WebView2, macOS WKWebView and Linux CEF export options.
It supports current-user stats, stats from other users, AVGRATE stats, progressive achievement notifications, aggregated global stats and history, and the current number of players. As well as a Game-Overlay-Activated trigger, usually used to pause the game.
Configuration
Stats and achievements must first be configured and published in the Steamworks Partner backend.
Use the configured API name exactly and select the matching stat type:
- INT: Signed 32-bit whole number.
- FLOAT: 32-bit floating-point number.
- AVGRATE: A moving average updated with the Update AVGRATE stat action.
Stats changed by this plugin must have Set By configured to allow the Client. Steam also enforces settings such as minimum value, maximum value, Increment Only, and Max Change. Invalid changes may be rejected when they are submitted.
The Steam client loads the current user’s stats before launching the game, so no separate request is required for current-user stats. Other-user and global stats must be requested before they can be read.
Storing changes
A StoreStats request has two stages:
- On Store stats request accepted means Steam accepted the request.
- On Steam stats stored success means Steam later confirmed that the data was stored successfully.
Steam attempts to store pending changes when the game closes. It also caches changes made while offline and submits them when the user is online again. However this should be treated as a fallback.
The Add stat action is a convenience operation that reads the current value, adds the supplied amount, and sets the result. It is not an atomic server-side increment.
Progressive achievements
A Steam achievement can be linked to a Progress Stat in the Steamworks Partner backend. Steam automatically unlocks the achievement when the linked stat reaches its configured unlock value.
Indicate achievement progress only requests a visual progress notification. It does not change the linked stat or unlock the achievement. The achievement must exist, be published, remain locked, and use a current progress value lower than its maximum.
Progress values must be positive whole values within the unsigned 32-bit range.
Achievement unlock and progress notifications depend on the user’s Steam notification settings and the available Steam interface support. Construct’s in-game Steam Overlay support is currently limited to Windows and Steam Deck. On macOS and other Linux systems, the interactive in-game overlay is unavailable, but Steam may still display achievement notifications through its fallback interface outside the game window.
Other-user stats
Call Request user stats successfully before reading another user’s stats.
Steam ID’s must be supplied as full SteamID64 decimal strings.
Other-user data is not refreshed automatically. Request it again when updated data is needed. Steam may also unload cached user data; after On user stats unloaded, request that user’s stats again before reading them.
Global stats
Global totals are only available for stats configured as Aggregated. Call Request global stats successfully before reading totals or history.
Up to 60 days of history can be requested. History values represent how much the stat changed on each day, not the cumulative lifetime total. Index `0` is today, index `1` is yesterday, and so on.
Aggregated INT totals use 64-bit integers and may exceed Construct’s exact numeric range. Use the string expressions for exact global totals or history values when large numbers are possible.
Client-controlled global stats can be manipulated by players. Configure sensible minimum, maximum, Increment Only, and Max Change restrictions, and do not use aggregated stats as trusted security-sensitive data.
Resetting and testing
Reset all stats is intended for development and testing. It resets the current user’s stats to their configured defaults, optionally clears achievements, and automatically stores the reset in Steam.
To test Steam functionality:
- Export using a supported desktop exporter.
- Keep Steam installed and running.
- Configure the App ID and enable Development mode in the official plugin while testing.
- Check
Is available before using Steamworks Stats functionality.
Before release, achievements may not appear in the Steam Community or library even when the API reports that they were unlocked.
Further documentation