Steamworks API wrapper and cmake file

[OTHGMars]

I've been working on updating AlterVerse to x64. After a couple times pulling in a branch, regenerating the project and having to link the Steamworks API to the build manually, I realized I needed a cmake file to eliminate that tedium. I placed that cmake file and my basic steamworks console wrapper into a branch that hopefully others can benefit from. If you're setting up a T3D build for steam, even if you don't use any of the code in this branch, the cmake file may save you some time.

I only use a couple functions from the steamworks API for getting the steam ID and display name for the current user. Thanks to @Steve_Yorkshire sharing his achievement code here, I was able to get console functions added for achievements. Even so, this barely scratches the surface of the functions the Steamworks API makes available.

The files are located at https://github.com/OTHGMars/Torque3D/tree/steamWrap. This is setup as a Module and static engine class so all interaction is through script and no existing engine source files are changed.

 

Usage

You will need to download and extract the steamworks sdk and have an App ID for your game. The new cmake options are:

TORQUE_STEAMWORKS – Check this to have steamworks added to the build.

TORQUE_STEAMWORKS_APPID – Enter the App ID for your game.

TORQUE_STEAMWORKS_REQUIRED – If this is checked, a distributed build of your game will not launch without steam running. An attempt to launch the game from the exe will exit, launch the steam client, then relaunch the game through steam with a logged in user. See here and here for more details.

TORQUE_STEAMWORKS_SDKPATH – Point this to the sdk directory within the extracted steamworks package.

Once configured, cmake will add the include directory, link the library, copy the correct .dll or .so and generate your steam_appid.txt file.

 

Console Functions

Because the static engine class is named SteamAPI, all function calls through script must be prefixed with SteamAPI::. Unless you know you're running a distributed build and have steamworks set to required, you should call SteamAPI::isSteamRunning() before calling any of the other functions. See the Steamworks API Reference and the console docs with the function declarations for more info.

SteamAPI::isSteamRunning() - Returns true if Steam is running and the Steamworks API has been initialized.

SteamAPI::getUserId() - Returns the steam ID for the currently logged in steam user..

SteamAPI::getPersonaName() - Returns the local players name.

SteamAPI::areStatsLoaded() - Returns true if a requestCurrentStats command has successfully completed for the current user.

SteamAPI::requestCurrentStats() - Requests an asynchronous stats load.

SteamAPI::setAchievement(name) - Unlocks an achievement.

SteamAPI::clearAchievement() - Resets the unlock status of an achievement.

SteamAPI::storeStats() - Upload stats to steam.

SteamAPI::getNumAchievements() - Get the number of achievements.

SteamAPI::getAchievementName(index) - Gets the 'API name' for an achievement.

SteamAPI::getAchievement(name) - Gets the unlock status of the Achievement.

SteamAPI::getAchievementDisplayAttribute(name, key) - Get general attributes for an achievement.

SteamAPI::resetAllStats(achievementsToo) - Resets the current users stats and, optionally achievements.

 

Callbacks

See https://github.com/OTHGMars/Torque3D/blob/steamWrap/Engine/source/steamworks/steamCallbacks.cpp#L30-L56 for complete callback descriptions.

 

Example Script

function onSteamUserStatsReceived(%success)
{
   %text = "The user stats load " @ (%success ? "Succeeded" : "Failed");
   echo(%text);
   if (%success)
      listSteamAchievements();
}
 
function onSteamGameOverlayActivated(%isActive)
{
   %text = "The steam game overlay is " @ (%isActive ? "Active" : "Inactive");
   echo(%text);
}
 
function listSteamAchievements()
{
   if (!SteamAPI::isSteamRunning())
   {
      echo("Steam is not running");
      return;
   }
 
   echo("Steam User: " @ SteamAPI::getPersonaName() @ ", Steam ID: " @
      SteamAPI::getUserId());
 
   if (!SteamAPI::areStatsLoaded())
   {
      echo("No Stats Loaded Yet!");
      return;
   }
 
   %numAchievements = SteamAPI::getNumAchievements();
   for (%i = 0; %i < %numAchievements; %i++)
   {
      %apiName = SteamAPI::getAchievementName(%i);
      %achieved = SteamAPI::getAchievement(%apiName);
      %dispname = SteamAPI::getAchievementDisplayAttribute(%apiName, "name");
      %dispdesc = SteamAPI::getAchievementDisplayAttribute(%apiName, "desc");
      %hidden = SteamAPI::getAchievementDisplayAttribute(%apiName, "hidden");
      %achievedText = %achieved ? ", Unlocked" : ", Locked";
      %hiddenText = %hidden ? ", Hidden" : "";
      echo(%i SPC %apiName @ ": " @ %dispname @ ", " @ %dispdesc @ %hiddenText @ %achievedText);
   }
}
 
if (SteamAPI::isSteamRunning())
   SteamAPI::requestCurrentStats();

[damik]

:o thank you

[OTHGMars]

New script calls and callback from ISteamUtils added with this commit.

SteamAPI::isOverlayEnabled ()

SteamAPI::isSteamInBigPictureMode ()

SteamAPI::isSteamRunningInVR ()

SteamAPI::setOverlayNotificationPosition (SteamNotificationPositions position)

SteamAPI::setOverlayNotificationInset (S32 xOffset, S32 yOffset )

SteamAPI::showGamepadTextInput (SteamGamepadInputMode inputMode, SteamGamepadInputLineMode lineMode, const char* description, U32 maxLength, const char* existingText )

onSteamTextInputDismissed(bool wasTextSubmitted, const char* newText, U32 textLength)

[OTHGMars]

ISteamController Interface

There is now an addon for the steamWrap branch that enables all features of the ISteamController interface. You can get it here.

If you're unfamiliar with the capabilities of Steam Input, I highly recommend the Dev Days presentation and Case-Study linked here for an eye-opening overview of the input tools available through Steamworks.

This branch contains the scripts and .vdf file needed to get started using SteamInput with the 'Full' template. To test:

1. Clone devhead and pull the steamInput branch.

2. Configure cmake as described in OP and select the additional TORQUE_STEAMWORKS_INPUT option.

3. Generate and build the project.

4. Rename the /Templates/Modules/controller_config/game_actions_T3D.vdf replacing “T3D” with your AppID.

5. Copy the controller_config directory to your steam install directory e.g. C:/Program Files/Steam/controller_config. Note: this will not affect your published game even if you have a published IGA.

6. Create a default configuration as described here.

7. Launch the game with steam running.

You can access the bindings panel at any time by entering SteamInput::showBindingPanel(0); into the console or activating the input you have bound to 'Bindings Panel' on the device.

The video below shows the code in action. It would be completely unremarkable except the keyboard or mouse were not touched even once while recording. All of the game input is coming from an xbox 360 controller.

k6B9dik6fJE

Without true controller (or even keyboard) navigation of guis, it will be hard to meet the requirements for the Steam Big Picture Icon and associated promotions. This is a small step in that direction though.

[Steve_Yorkshire]

Coolio