Steamworks API Exploration

Long story short, I wanted to try out the Steamworks API. So me and my friends did a game Flatshot, uploaded it to Greenlight, got greenlit and now we have access to Steamworks. Quest complete!

This article explains how Steamworks works just in case someone ~ Lutris cough ~ wants to make a similar API. Steamwoks covers a lot of stuff such as VR, inventory, a mods manager (they call it user generated content), game uploads (they call it depots), a cloud file service (they call it steam cloud) etc... But this time I'll focus on the Leaderboards, Stats and Achivements API because I have implemented on Flatshot.

Pros and Cons


  • It works!: A lot games has been using it for a long time.
  • New features: Valve adds new features from time to time.
  • Cross platform: Supports Linux, OSX and Windows.


  • Is privative: It's not compatible with free as in freedom (GPL) games.
  • Documentation: The documentation is not easy to read. But probably I feel this way because I'm used to free software documentation made by the community with love.
  • Rudimentary: It doesn't use a Token Based Auth or whatever to be accessed directly. Instead, every game has to compile the Steamworks client library code. Which brings us to...
    • Language dependent: The only official languages are C and C#. There are a lot wrappers but they are not easy to write.
    • It doesn't works with MinGW: In Windows, it only works with Visual C++. On top of that, users have to install additional .Net libraries. So wierd... This is another derivative problem of not using a Token Based API.
    • Difficult to maintain: For Valve, it's difficult to make updates because they have to update the server and the client. And the documentation for both.


There are two interfaces for development: The Console and The API.

The Console

The console is a web app where the devs create Stats, Achievements and Leaderboards. We access it through once the game has been Greenlit.


Stats lets us store specific data for each player. Can be used to store statistics (ex. number of kills), scores (ex. best time), remember small configuration (ex. volume) etc...

In the console, the devs can set the following attributes:

  • ID Autogenerated
  • Type Can be a INT, FLOAT, or AVGRATE
    • INT A 32-bit (signed) integer.
    • FLOAT A 32-bit floating point value.
    • AVGRATE An average.
  • API Name This is used to reference the Stat internally (programmatically). I think this should't exist, the auto generated ID should be enough.
  • Set By Who can modify the stat.
    • Client The game downloaded from steam.
    • Game server A server hosted by the players.
    • Official game server A game server hosted by the devs.
  • Increment Only?
  • Max Change
  • Min Value
  • Max Value
  • Default Value
  • Aggregated Global stats that are set by all players.
  • Display Name Name of the stat visible to players.

Stat creation screen in the console


  • ID Autogenerated.
  • API Name This is used to reference the Achievement internally (programmatically). I think this should't exist, the auto generated ID should be enough.
  • Progress Stat Binds the achievement to a stat so the players can keep their progress.
  • Display Name Name of the achievement visible to players.
  • Description Description visible to players.
  • Set By Who can modify the stat.
    • Client The game downloaded from steam.
    • Game server A server hosted by the players.
    • Official game server A game server hosted by the devs.
  • Hidden If true, a "hidden" achievement does not show up until they have achieved it.
  • Achieved Icon
  • Unachieved Icon

Achievement creation screen in the console

Stats and Achievements can be shown on each player profile, as you can see, players can keep track of stats that are bound to an achievement


  • Name This is used to reference the Achievement internally (programmatically). I think this should't exist, there should be an autogenerated ID instead.
  • Community name Name visible to players
  • Sort method
    • Ascending
    • Decending
  • Display type
    • Numeric
    • Seconds
    • Milliseconds
  • Writes I'm not sure how this works. I think that if this is set, the players can't set the scores directly, only a server hosted by the devs can.
  • Reads I'm not sure how this works. I think this means that if this is set, the api will only return the friends entries. This doesn't makes sense to me because the API has an option to retrieve the global leaderboard and the friends only one which makes this option useless.

Lederboard creation screen in the console


Once the Stats, Achivements and Leaderboards are set on the Console, we can manipulate them trough the API in game.

My wrapper

I did a wrapper on C++ and then used it on Flatshot. I'm working on it on a private repository because I have a setup that involves Valve code, however I uploaded al the code I wrote in this repo. This wrapper is used by the game engine I'm writing, The Rosalila Engine which is used by The Shooter Engine a shoot em up engine I'm writing too.

All the functionality I have written so far can be summarized in this header. It involves Stats, Achivements and Leaderbards.

I won't deepen into it here because it is quite harsh and I just don't see the point. Instead, I'll talk about how would it look if it was implemented on a Token Based API.

How would this look if it was made with a Token Based API?

I wrote this documentation to explain how would the API look if it was using a modern Token Based API. I hope it helps!

Final thoughts

I love how Valve handle their stuff. I love their software and games. Also, I like how they work together as an horizontal team and how they innovate. I don't mind their API being so rudimentary and outdated. What I don't understand is why are they falling behind in terms of free software.

  • They say that they encourage the modders community. Isn't free software the ultimate form of modding?
  • They say they love innovation. Isn't free software the most efficient way to innovate? (patents? yeah right...)
  • They say they like horizontal relationships with working partners. You can't get more horizontal with free software.
  • They want money? Free software has the most scalable economic models.

I'm really curious of what they think about all this. I hope they open their doors to free software, and I'm up to help them on the transition, because they have done great stuff to the gaming and software community and I just don't want them to fall behind.

Anyhow, there are a lot great projects related to gaming in the free software community, such as engines, games or players comunities. So I'll continue to work on those projects because that's where the action is.

Ahmed Castro

Read more posts by this author.

Subscribe to Rosalila Studio

Get the latest posts delivered right to your inbox.

or subscribe via RSS with Feedly!