1
Scripts, plugins, utilities, goodies / Steam plugin
« on: October 19, 2013, 12:28:02 PM »
Steam plugin for WME
If you are lucky enough to have your game published on Steam, this plugin will allow you to leverage some of the Steam features, namely achievements and game stats.
Getting started
Download the plugin here: http://dead-code.org/download/wme_steam_125.zip
Source code is also available: https://bitbucket.org/MnemonicWME/wme_steam_plugin/
Accessing Steam functions from WME scripts
First you need to create a SteamAPI object and store it in a global variable. Typically you will do this when the game starts, i.e. somewhere in the beginning of game.script:
To check whether the initialization was successful, check the SteamAvailable property.
If the SteamAvailable property is false, something is wrong. The typical reasons are that either the Steam client is not running or you've provided an invalid game ID (see above).
Working with achievements
To unlock an achievement, call the SetAchievement method. It accepts a string ID of the achievement (the ID you assigned to your achievement when defining it) and it returns true/false, depending on the success. It is safe to call this method multiple times, if the achievement is already unlocked, subsequent unlock attempts will be ignored.
This is pretty much everything you will typically need. The plugin provides more functions, though:
To check whether an achievement has already been unlocked by the player, use the IsAchieved method:
To reset an achievement back to unlocked state, use the ClearAchievement method. You will probably only need this for testing purposes, not in the actual game:
To query all achievements defined for the game, use the NumAchievements property and GetAchievementId method. The following example will print out all achievement IDs:
Working with stats
Stats are some persistent values related to your game, stored by Steam across multiple gaming sessions. You can use them for tracking information such as the number of times the player started your game, the number of miles the player traveled in total etc. Steam can store either integer numbers or float (decimal) numbers. Just like with achievements, you define stats using the Steam partner site.
To store a stat value, use the SetStat method. It accepts either integer or float numbers. If unsure about the value of your variable, convert it explicitly using the ToFloat() or ToInt() WME functions.
To retrieve stored stats, use either the GetStatInt or GetStatFloat method:
Other functions
For testing purposes you may need to clear all stats and achievements. To do that, use the ResetAllStats method. It accepts a logical argument, specifying whether you want to reset just stats or also all achievements:
To reload the stats/achievements states from the server, use the RequestStats. Normally you shouldn't need to call this method. The plugin will call it automatically upon initialization.
To check whether the stat/achievement info is available, use the StatsAvailable property. Stat info is downloaded from Steam asynchronously, meaning that there may be a slight delay between plugin initialization and stats becoming available. Until this property is true, all other calls to methods dealing with stats and achievements are ignored.
You can query the game ID using the AppId property:
If you are lucky enough to have your game published on Steam, this plugin will allow you to leverage some of the Steam features, namely achievements and game stats.
Getting started
Download the plugin here: http://dead-code.org/download/wme_steam_125.zip
Source code is also available: https://bitbucket.org/MnemonicWME/wme_steam_plugin/
- Copy wme_steam.dll (the plugin itself) and steam_api.dll (Steamworks API library) to your WME installation directory.
- The Steam library needs to know the unique ID of your game (you will get the ID once your game is accepted to Steam). If the game is executed from the Steam client, it already knows the ID. However for testing purposes, you will need to create a text file in your WME installation directory, called steam_appid.txt. This file will contain the ID of your game.
- Define your game's achievements and stats using the Steam partner site (notice that each achievement and stat is identified by a unique string ID).
Accessing Steam functions from WME scripts
First you need to create a SteamAPI object and store it in a global variable. Typically you will do this when the game starts, i.e. somewhere in the beginning of game.script:
Code: WME Script
- global g_Steam = new SteamAPI();
To check whether the initialization was successful, check the SteamAvailable property.
Code: WME Script
- if (g_Steam.SteamAvailable) ...
Working with achievements
To unlock an achievement, call the SetAchievement method. It accepts a string ID of the achievement (the ID you assigned to your achievement when defining it) and it returns true/false, depending on the success. It is safe to call this method multiple times, if the achievement is already unlocked, subsequent unlock attempts will be ignored.
Code: WME Script
- g_Steam.SetAchievement("ACH_WIN_ONE_GAME");
This is pretty much everything you will typically need. The plugin provides more functions, though:
To check whether an achievement has already been unlocked by the player, use the IsAchieved method:
Code: WME Script
To reset an achievement back to unlocked state, use the ClearAchievement method. You will probably only need this for testing purposes, not in the actual game:
Code: WME Script
- g_Steam.ClearAchievement("ACH_WIN_ONE_GAME");
To query all achievements defined for the game, use the NumAchievements property and GetAchievementId method. The following example will print out all achievement IDs:
Code: WME Script
Working with stats
Stats are some persistent values related to your game, stored by Steam across multiple gaming sessions. You can use them for tracking information such as the number of times the player started your game, the number of miles the player traveled in total etc. Steam can store either integer numbers or float (decimal) numbers. Just like with achievements, you define stats using the Steam partner site.
To store a stat value, use the SetStat method. It accepts either integer or float numbers. If unsure about the value of your variable, convert it explicitly using the ToFloat() or ToInt() WME functions.
Code: WME Script
To retrieve stored stats, use either the GetStatInt or GetStatFloat method:
Code: WME Script
Other functions
For testing purposes you may need to clear all stats and achievements. To do that, use the ResetAllStats method. It accepts a logical argument, specifying whether you want to reset just stats or also all achievements:
Code: WME Script
- // reset just stats
- g_Steam.ResetAllStats(false);
- // reset both stats and achievements
- g_Steam.ResetAllStats(true);
To reload the stats/achievements states from the server, use the RequestStats. Normally you shouldn't need to call this method. The plugin will call it automatically upon initialization.
Code: WME Script
- g_Steam.RequestStats();
To check whether the stat/achievement info is available, use the StatsAvailable property. Stat info is downloaded from Steam asynchronously, meaning that there may be a slight delay between plugin initialization and stats becoming available. Until this property is true, all other calls to methods dealing with stats and achievements are ignored.
Code: WME Script
- if (g_Steam.StatsAvailable) ...
You can query the game ID using the AppId property:
Code: WME Script
) and I don't have time delve into it right now. But maybe you know of some skilled Linux developer who would be interested in helping with the project (or maybe you are one!). If so, please point them in this direction 
Rock on! 
