Unaffiliated

Overview

The Steam Input API is designed to allow you to easily enable full support for Steam Input devices in your game. We define full support as the follows:

• Your game uses the proper controller-specific glyphs when showing in-game input prompts.
  
• The Steam Input configurator screen uses in-game actions that the player performs in your game, instead of keys or buttons.
  
• You've published an official configuration for the controllers you support.
  
• Your game doesn't restrict the user's ability to customize their controls. This means it allows any mix of mouse, keyboard, or gamepad input simultaneously.
  
• When your game wants keyboard input (e.g. when naming avatars), you use the API to automatically bring up the text entry UI.
  
• Your game has no launchers that require mouse or KB input - or even better, no launcher at all.

To ensure users have a good experience from the couch, we also recommend the following:

• Make your UI readable from several feet away. Our rule of thumb: when your game is running at 1920x1080, your fonts should be a minimum of 24px in size.
  
• Start your game in fullscreen by default when the user is running Steam Big Picture (the "SteamTenfoot" environment variable will be set)
  
• For bonus points, at first launch detect the user's screen resolution and set your resolution to match it.

Common Use Cases

I'm Adding Steam Input API support before shipping my game

Great! Follow the technical directions in Implementing Steam Input API support.

I'm Adding Steam Input API support alongside other input libraries

It's perfectly acceptable to ship conventional gamepad input as well as Steam Input, and if you're adding Steam Input API support after initial launch, or shipping your game on stores other than Steam, you could easily find yourself in this situation. There's a few things to keep in mind:

1. Be deliberate with your analog action choices
There's a lot to this one, so let's break it down:

• Avoid using the the system mouse ("os_mouse" option) unless you have a good reason to need it. Being able to determine if input comes from a real mouse vs a controller is an important part of good UX practices.
  
• You should either rely on the configurator to provide sensitivity (ie you don't filter incoming Steam Input data), or you should use a dedicated sensitivity option for Steam Input that's distinct from the system mouse.
  
• You should always be using mouse-like input for cursor or camera controls. Joystick style analog actions should be reserved for directional input like aim in a twin stick shooter or performing tricks in a snowboarding game.

2. Be consistent with auto-aim on joysticks
If you have any auto-aim or aim-assist applied to XInput analog sticks, consider applying that to Steam Input devices as well, at least for traditional controller models configured through Steam Input. You can call GetInputTypeForHandle to determine an individual controller's model type.

3. Use SDL version 2.0.6 or above, if possible
If you're using SDL (Simple DirectMedia Layer), one of the most popular cross-platform game libraries for handling things like input, make sure you're using the latest version, or at least version 2.0.6 or above. This version allows Steam to tell SDL to ignore input for controllers configured by Steam Input, which avoids double-input bugs.

4. Careful with XInput opt-in
If you're keeping raw XInput support in your game, don't use the partner site to opt all Xbox controllers into Steam Input. Users who want to opt in themselves still can, but users who are happy with using raw XInput for their controllers might get annoyed at being forced to reconfigure their device in the Steam Input configurator.

5. Keep external configuration tools organized
If you're not relying on a library, but instead on a third-party tool like Joy2Key for gamepad input, you should take special care and make it very clear to the player (and yourself) when it's active and when it's not, so that you don't "cross the streams" with Steam Input and cause double-input bugs.

I Want my Non-Steam Input API Games to Play Nicely with Steam Input

First of all, I highly recommend reading Zach Burke's The Five Golden Rules of Input.

To summarize, they are:

1. On-screen icons should match the input device
   
2. Mouse cursor should match the input device
   
3. All devices should work 100% of the time
   
4. Dpad, analog stick, and mouse can all be used to navigate menus
   
5. A disconnected gamepad should pause the game

These are good general guidelines to follow if you are able. To add our own emphasis:

Gamepad and mouse input should be possible simultaneously

Most games allow mouse input, or gamepad input, but not both at the same time, and this is the chief cause of compatibility issues with the Steam Input system.

Additionally:

1. Set a recommended controller configuration for all controller types
   This way Steam doesn't have to prompt the user to select a configuration on startup. By the way, you don't need to provide a configuration for both the Xbox 360 and the Xbox One controllers -- if you only supply one, it will work for the other model.
   
2. Opt-in Controller Type you don't have native support for to Steam Input
   If you don't have built-in support for these controller types, you should use the partner site to opt them in to using Steam Input. See the bottom of this section for more on that.
   
3. If you're not going to allow simultaneous gamepad/mouse...
   ...at least make the deadzone, acceleration, and sensitivity of the joystick configurable. Joystick emulation for the trackpad works by rapidly flicking the virtual joystick so it is quite sensitive to these settings. For good results you want to allow very high sensitivities, deadzones that go to 0 and a linear acceleration curve. Shadow of War's controller settings are a good example of this.
   
4. Allow users to select from Xbox or PS4 glyphs via the menu or detect the device type via our API
   Since Steam Input can send emulated / reconfigured input, a conventional input system might detect the player's device as something other than what they're actually using. Allowing them to manually change the on screen glyphs to compensate is a nice touch. To set a nice default in the absence of information from the player, you can use the API to get a controller handle for any given XInput slot and query what its controller model is -- even if you're not using the full Steam Input API

If your game doesn't use Steam Input natively, that means players will rely on legacy configurations. That said, you can set the tone for your game with a good default confirguration.

Selecting a configuration for my non-Steam Input API Game

Ideally developers would play their game with each type of controller and develop a config that plays well with their game. However, for your convenience we've also make a series of templates which are intended for specific game genres, To set one of these templates as a recommended config please follow the instructions in this section, but when you get to the configuration drop down select the desired template instead of the "Custom Configuration" option.

Steam Controller Templates

• Gamepad With High Precision Camera/Aim - This configuration is the ideal configuration for an FPS or any game using camera controls. Be careful to test that your game supports simultaneous gamepad/mouse before selecting this, including any ancillary screens such as inventory or map screens.
  
• Gamepad With Mouse and Gyro - We feel that Motion Controls are great for aiming, but not all users will be used to them. As with the "Gamepad With High Precision Camera/Aim" template, make sure your game fully supports simultaneous gamepad/mouse before selecting.
  
• Gamepad with Camera Controls - This configuration takes mouse-style input from the trackpad and translates it into flicks of an emulated joystick. If your game can be configured to have very high joystick sensitivity, no deadzone, and a linear acceleration curve this configuration can work well, otherwise please consider using a mouse/keyboard config instead.
  
• Keyboard (WASD) and Mouse - Maps the standard FPS control scheme onto a controller. Note that this config assume your use/pickup action will be bound to "E" and not "F".
  
• Gamepad - This emulates an Xbox controller with the right trackpad being turned into a raw emulated joystick. Perfect for twin-stick, platformer, or sports games.

Playstation 4 Controller Templates

• Gamepad With High Precision Camera/Aim - This configuration emulates mouse input with the trackpad and right joystick. Be careful to test that your game supports simultaneous gamepad/mouse before selecting this, including any ancillary screens such as inventory or map screens.
  
• Gamepad With Mouse and Gyro - We feel that Motion Controls are great for aiming, but not all users will be used to them. As with the "Gamepad With High Precision Camera/Aim" template, make sure your game fully supports simultaneous gamepad/mouse before selecting.
  
• Keyboard (WASD) and Mouse - Maps the standard FPS control scheme onto a controller. Note that this config assume your use/pickup action will be bound to "E" and not "F".
  
• Gamepad - This emulates a standard Xbox controller with the addition of the trackpad emulating right joystick. Perfect for twin-stick, platformer, or sports games.

Xbox Controller and Generic Gamepad Templates

• Keyboard (WASD) and Mouse - Maps the standard FPS control scheme onto a controller. Note that this config assume your use/pickup action will be bound to "E" and not "F".
  
• Gamepad - This passes through the gamepad controls without remapping. Perfect for any game that already supports Xbox controllers.

Automatic Action Set Switching

Normally, legacy mode action sets must be activated by the player themselves as the game has no knowledge of Steam Input. However, the configurator is able to detect when the mouse cursor appears and disappears, and you are able to use this as an event to drive action set changes.

To configure this, first select an action set in your configuration, then select "Manage Action Set" at the bottom of the configuration screen. This screen should pop up:



This is another tool in your belt for properly differentiating between mouse-like input and gamepad-like input, even if you aren't using the native Steam Input API.

Text Input

On-screen text input is not technically part of the ISteamController (Steam Input) API, but is found instead in ISteamUtils.

Some quick references:

• ShowGamepadTextInput
  
• GetEnteredGamepadTextLength
  
• GetEnteredGamepadTextInput

You might find these useful regardless of whether you're using Steam Input in any way.

Implementing Steam Input API support

The implementation process is straightforward, and shouldn't take more than a few days of work. Four steps are involved:

1. In a text editor, create an in-game actions file, which tells Steam what in-game actions your players can bind to the controller.
   
2. In Steam, use the Steam Input configurator UI to create your default configuration.
   
3. In your game, use the Steam Input API to read actions from the controller, and to retrieve appropriate glyphs for display.
   
4. Update your game depot with the new binaries, and publish your configuration as the official config.

Step 1 - Creating an In-Game Actions File

Start by downloading the starting in-game actions (IGA) file. Place it in your "<Steam Install Directory>\controller_config" directory (create the directory if it doesn't exist). Rename the file to the following: "game_actions_X.vdf", where X is your game's Steam AppID. If you don't know what your game's Steam AppID is, it can be found by logging into your Steam partner site.

Now open up the file in your favorite text editor. The file is in a standard Valve format called KeyValues, which is a simple & easily read format. You might also find it useful to download one of our In-Game Actions File Templates or the Portal 2 IGA for a reference.

For more details see: In-Game Actions File

File Format

IGA files contain an "actions" section, which should list all the in-game action sets (IGAS) in your game. An IGAS describes all the actions a player can take within some game context - such as when the player is in a vehicle, or on foot, or navigating the menu system. For each IGAS, the Steam Input configuration UI will provide a tab that allows a player to customize how those actions are bound to the controller.

An IGAS entry in the IGA file should contain a "title" key & value, and the following subsections: "StickPadGyro", "AnalogTrigger", and "Button". The "StickPadGyro" and "AnalogTrigger" sections each contain a list of IGAs that the player can only assign to the stick/pad/gyro and analog triggers respectively. The "Buttons" section contains IGAs that can only be bound to digital inputs (like the physical ABXY buttons, or a trackpad that's in ABXY mode, or a trigger that's not being used as an AnalogTrigger action).

Designing your IGA

Take a minute to think about the functionality of your game - how many distinct modes does it contain? For each place where you want to have distinct controls you'll want to make an action set. Most games will have at least a distinct "Menu" and "In-game" action set, but many will need more. Does your game have any special cases like operating a vehicle or have specialized in-game menus like a map or inventory screen, those may also be useful to make into action sets.

Not everything needs to be a distinct action set though, you can also use action set layers to handle similar modes. For example if you have can drive both a car and boat in your game you may want to include one "vehicle" action set with an action set layer of "boat" or "car" on top of it. Action set layers retain any settings of the parent action set and can make understanding and editing configurations more manageable for both your development team and your users.

For more information on action set layers see: Action set layers

Button Actions

The format for "Button" actions is as follows:


The <action name> is the internal name you want to refer to this action by in your game code, when talking to the Steam Input API. The <localization key> should be the name of an entry in your localization section (see Adding Localization). Make sure to include the '#' character at the start of your localization key.

Analog Trigger Actions

The format for "AnalogTrigger" actions is the same as for "Button". "AnalogTrigger" actions should be actions that your game will be interpreting as full analog inputs, like vehicle acceleration. If you don't have any of that kind of input, just leave the section empty. The Steam Input configurator UI will allow players to assign any "Button" action to the physical triggers if they're not being used as an "AnalogTrigger" action.

StickPadGyro Actions

The format for "StickPadGyro" actions is as follows:


<action name> and <localization key> are the same as the matching keys in the "Button" format. <analog mode> tells us how to interpret the data coming from the physical controls, before we pass it to your game via the steam input API.

Valid <analog modes> are as follows:

• "absolute_mouse" - for when you're expecting the action to behave like a mouse. Useful for first or third person camera, or an actual mouse cursor.
  
• "joystick_move" - for when you're using the action to move a character around.

There is one optional setting for StickPadGyro actions that are using "absolute_mouse" as their input. If you set the "os_mouse" key to "1", we'll pass the input from the player into the OS as well as your game. This is useful if you have a visible OS mouse cursor that should be controlled by this action.

Here's an example:

Step 1.1 - Adding Localization

The "localization" section in your IGA file contains a list of languages, each of which is a section containing localization keys & values. For example:


The actions in your IGA file should then specify their names by referring to the desired localization key, preceded by the '#' character. Here are example actions using the above localization keys:


If the language the game is running under is not found in the localization section, English will be used as a fallback. If English is not found, the string will be shown as is. Supported languages are as follows:

• brazilian
  
• bulgarian
  
• czech
  
• danish
  
• dutch
  
• english
  
• finnish
  
• french
  
• german
  
• greek
  
• hungarian
  
• italian
  
• japanese
  
• koreana
  
• korean
  
• norwegian
  
• polish
  
• portuguese
  
• romanian
  
• russian
  
• schinese
  
• spanish
  
• swedish
  
• tchinese
  
• thai
  
• turkish
  
• ukrainian

Step 1.2 - Titles & Descriptions

Configurations also need a localized title and description. If you're only making a single official configuration for your game, you don't need to worry about this - we'll provide a default title and description, and you can skip this step entirely. But if you want to have multiple official configurations for your game, then you'll also need to provide localized titles and descriptions for them.

Configuration titles and descriptions should be listed along with the rest of your localization keys. The title key must start with "Title_", and the description key must start with "Description_". Here's an example:


When you publish a configuration (see Step 4 - Publishing), you'll be able to select which of these localized titles and descriptions you want to use.

Step 2 - Creating a Default Configuration

Once you've created your IGA file, and ensured it's in the right directory & named to match your game's AppID, you're ready to create a configuration.

Run Steam in Big Picture mode, and navigate to your game's game details page.

Select "Manage Game," and then "Configure Controller." If you receive any errors at this point, they'll be identifying issues in your IGA file and you'll need to go fix them - the most common mistake is a missing closing quote or brace.

If you don't receive any errors, you're now looking at an empty controller configuration for your game, and it should be fully aware of your in-game actions. Use the UI to create a default configuration. Make sure you set defaults for all your in-game action sets, not just the first one.

Once you've got a configuration, save it privately. Don't publish it, because your game is not yet ready to receive IGAs.

Step 3 - The Steam Input API

Make sure you have the latest version of the Steamworks API - Grab it from the Getting Started With SteamWorks page.

Add the following command line parameters to your Steam shortcut:


This will tell steam to keep the controller locked to your game. Usually, the controller flips its configuration as focus shifts from your game to steam or the desktop, because we use different configurations for each of those states. This can make it trickier to debug the controller while you're working on it, because the controller will change its configuration when you hit a breakpoint in your debugger. Setting this -forcecontrollerappid option will keep the controller locked to your game. This may have the side effect of making it less/non-functional in the desktop or steam overlay.
You can also download the official controller glyph renders or their PSD source. This is only really necessary if you want to use these as a starting point for your own art. Otherwise, you can just use the API to get a direct file path to appropriate art for any controller input (the image files are shipped with the Steam client itself).

Step 3.1 - API Overview

The Steam Input API is built around the in-game actions & sets that you specified in your in-game actions file in Step 1.

For a complete API reference, see ISteamController Interface

The functionality overview is as follows:

• On game startup, initialize Steam Input with ISteamController::Init, use the ISteamController::GetActionSetHandle, ISteamController::GetDigitalActionHandle, and ISteamController::GetAnalogActionHandle functions to resolve the action & set names into handles. Use these handles to identify actions & sets throughout the rest of the API.
  
• Use ISteamController::GetConnectedControllers to detect when a controller exists. Use the handles it returns to identify controllers throughout the rest of the API.
  
• Use ISteamController::ActivateActionSet / ISteamController::DeactivateActionSet to control which controllers are bound to different action sets, and if you're using action set layers, Use ISteamController::ActivateActionSetLayer / ISteamController::DeactivateActionSetLayer.
  
• Use ISteamController::GetDigitalActionData and ISteamController::GetAnalogActionData to read the input state of all your in-game actions. You may call ISteamController::RunFrame right before to get the freshest data or you may rely on calling SteamAPI_RunCallbacks elsewhere in your game.
  
• Use ISteamController::GetDigitalActionOrigins and ISteamController::GetAnalogActionOrigins to get the origin(s) that the player has assigned to your in-game actions, and show the appropriate glyphs in your onscreen UI.
  
• Use ISteamController::ShowBindingPanel to pop up the Steam overlay directly into the controller configuration for a specified controller. This means you won't need to make a customization UI.
  
• Use ISteamController::GetInputTypeForHandle if you want to identify each controller's device model so you can use matching art in game. This is useful for e.g. player seat selection screens as seen in couch co-op games, sports games, etc.

Step 3.2 - Input Handling

For digital actions, the data returned by ISteamController::GetDigitalActionData is straightforward:


For analog actions, the data returned by ISteamController::GetAnalogActionData is only slightly more complex:


While you're in your code, make sure you're not preventing the user from combining different kinds of input simultaneously. A common mistake we've seen is for games to start ignoring gamepad input when they see mouse & KB, or vice versa.

Step 3.3 - On-screen Glyphs

To display an on-screen prompt for your controller, you need to get the physical origins that are bound to an in-game action. The player may have bound more than one physical origin to the same action, so it's best to have your UI cycle through displaying each origin. ISteamController::GetDigitalActionOrigins and ISteamController::GetAnalogActionOrigins will return the count of origins for the specified action, and fill out the passed in originsOut array.

For each origin, you can use the ISteamController::EControllerActionOrigin enum to remap the origin to a corresponding image. You may provide your own images for the controller glyphs, but we generally recommend that you use the ISteamController::GetGlyphForActionOrigin API call. When you call this function with an origin enum, it will return a local filepath to a .png file for the corresponding controller glyph from Valve's official image set (located in the Steam client's install folder).

This method supports all hardware devices recognized by Steam Input (so a PlayStation controller will show PlayStation buttons, and an Xbox controller will show Xbox buttons, etc). Even better, it's future proof -- when Valve adds support for new hardware, this function will automatically fetch updated glyphs without you needing to recompile your game with new glyph assets. If you do decide to include your own custom glyph assets, you should at least check for the case where your asset set does not have a matching glyph for the provided enum value, and fall back to ISteamController::GetGlyphForActionOrigin. This way the glyph will always have something displayable and won't simply be blank.

Step 4 - Publishing

Once your game is working with the controller, you're ready to publish. You'll need to release your new game update and make your configuration the official one. Official configurations are automatically loaded when a player launches your game for the first time. This allows users to simply fire up your game and play without needing to go into the configuration screen at all.

Here's the recommended process:

Step 4.1 - Update your game

• Update your Steam depot with your new version of the game

Step 4.2 - Publish your configuration

• Run Steam in Big Picture mode and navigate to the default configuration you created in the controller configuration.
  
• Hit the (Y) button, or click the "Save As" button at the bottom of the screen.
  
• Select the desired localized title & description in the popup, change it to a PUBLIC profile, and click the PUBLISH button.
  
• You will get a confirmation, and the file ID of the public configuration. Copy/save the ID.

Step 4.3 - Make the configuration official

• Open up your game's page on the steam partner website.
  
• Select "Steam Controller" from the "Application" tab.
  
  
  
• Scroll to the section called "Controller Template". Select the "Custom Configuration" option in the dropdown. (If you were not planning on adding native support and just want to select from common legacy mode presets, here is where you would do so).
  
  
  
  And from the selection below, select "Add Custom Configuration."
  
  
  
  
• Paste the file ID of your public configuration into the box, and click the Save button.
  
  
  
  
• Publish your app changes in the partner site as usual.

You can keep making changes to your official configuration even after you've published and made it official. All you have to do is re-publish the configuration through the Steam Input configurator screen, and users will get the updated one automatically. You won't need to go through the step of making it official again.

If you'd like, you can also specify multiple official configurations for your game. You may want to create an official "Southpaw" (left-handed) mode, for example.

To do this, simply create multiple configurations and publish them each via step 4.2. Then, in step 4.3, paste all the file IDs for your configurations into the box, separated by the comma character (,) characters. The first one on the list will be considered the highest priority, and will be picked by default for new players. Don't forget to make Titles & Descriptions for each of them.

When your official configurations have been posted they will appear in the "Custom Configuration" section:



For each configuration you can get a direct link, see what controller type it is for, control which beta branches it is available on, or remove it entirely. If you create a new official configuration, you can use the remove / add functions in this section to replace an existing one.

At the very bottom is an opt in for third party controller types:



Checking these boxes will cause those controller types to make use of Steam Input rather than their standard gamepad input protocols.

Tips

Dedicated Menu Actions

We recommend creating a separate in-game action set for your menu controls, instead of just re-using actions in your main game set. Most customers won't need to modify this menu controls set, but it's an easy way to provide the capability to players who actually need it (as can be the case for some disabled gamers, for example).

Custom Icons

The Steam Input system can also create several styles of on-screen menus. Putting your own .png icons in <your base game directory>/TouchMenuIcons/*.png will show them first in the list for your game's touch/radial menus. This will allow you to set up your own on-screen radial menus or touch menus with icons bound to specific actions without doing any game/UI code. As a developer you may wish to do this even if you don’t actually have any radial or touch menus in your own default configuration. Since any user modified configurations will also have access to these, users will be able to create nicely themed menus using your official icon art.