Wintermute Engine > Scripts, plugins, utilities, goodies

Steam plugin

(1/6) > >>

Mnemonic:
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/
[*]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).
[/list]

Note: If your game is not on Steam yet and you want to test the Steam integration anyway, you can use a test game called Spacewar. Its ID is 480 and the defined achievements are listed on this site


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) ... 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.

--- 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 ---Game.Msg(g_Steam.IsAchieved("ACH_WIN_ONE_GAME")); 
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 ---for (var i = 0; i < g_Steam.NumAchievements; i = i + 1){  Game.Msg(g_Steam.GetAchievementId(i));} 

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 ---g_Steam.SetStat("NumGames", ToInt(10));g_Steam.SetStat("FeetTraveled", ToFloat(100.5)); 
To retrieve stored stats, use either the GetStatInt or GetStatFloat method:

--- Code: WME Script ---Game.Msg(g_Steam.GetStatInt("NumGames"));Game.Msg(g_Steam.GetStatFloat("FeetTraveled")); 

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 statsg_Steam.ResetAllStats(false); // reset both stats and achievementsg_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 ---Game.Msg("Current game ID is: " + g_Steam.AppId); 

Mnemonic:
What if my game is already on Steam and I want to add achievements?

Ok, it's a little tricky, because even if you add the plugin initialization to game.script, when the player loads an old saved game with old game.script, the plugin won't get initialized.

You will need to find a way to "inject" the plugin initialization to an existing game. To do that, I recommend finding some script that isn't running all the time, but it's likely to get executed eventually. For example, is there a scene in your game where the player keeps returning to? Patch the script of this scene and add some code to initialize the plugin:


--- Code: WME Script ---global g_Steam; // if the variable is empty, it means the player is running an old game.script// so we'll just initialize the plugin nowif (g_Steam == null){  g_Steam = new SteamAPI();    // you may also want to unlock some achievements the player may have missed so far  if (someGameVariable) g_Steam.SetAchievement("SomeAchievement");}   
However, since the g_Steam variable may or may not be initialized (depending on whether the player visited the "injection" scene yet), you need to be careful when calling any method:


--- Code: WME Script ---// always make sure the plugin is initalized before calling SetAchievementif (g_Steam != null){  g_Steam.SetAchievement("SomeAchievement");} 

Azrael:
Thanks a lot  :)

hubertMichael:
WOW :D You are great :D Thank you :D

metamorphium:
Thank you! This couldn't have come in a better time. :)

Navigation

[0] Message Index

[#] Next page