Steamworks Documentation
General Concepts

Steam Input

"Steam Input" is the umbrella term referring to the entire collection of software, hardware, and configuration utilities that Steam uses to interface with games.

Steam Input Configurator

The Steam Input Configurator (SIC) is built into the Steam client and sits between the player and their game/application. The SIC receives input from your input device, and translates that data appropriately depending on the player's settings before passing it along to the game.

The SIC can be used in two main ways: legacy mode and native mode.

Legacy Mode

Legacy mode is a compatibility mode designed for games that have not implemented the Steam Input API. In this case, the SIC just serves as a really fancy input mapper that any player can use for any game on Steam.

The player can remap any physical input to any other physical input -- such as making the "A" button simulate the keyboard "Enter" key, make a full pull of the left analog trigger simulate a mouse click, etc. This mode works with any supported input device, not just the Steam Controller.

Legacy mode is great for working with games that never supported the API, but there are limitations to it. For one, games programmed in such a way to assume that gamepad and mouse controls will never both be active simultaneously have been known to suffer from all manner of glitches when your configuration violates those assumptions. Also, the game will have no idea you're even using the configurator (it's just receiving low-level hardware inputs that the configurator is spoofing) so the on-screen glyphs for controller inputs will probably not match up.

Native Mode

In Native mode, the game receives input data directly from the configurator in the form of "actions." The idea here is that the game itself has no knowledge of what actual inputs are driving said actions, simply that the actions are happening. All configuration and control settings are relegated to the Steam input configurator. That said, the game can request information via a special API call about which physical controls are bound to which actions purely for the purpose of displaying appropriate on-screen glyphs.

Steam Input API

The Steam Input API is the application programming interface developers use to talk directly to the SIC in Native mode. The API is not necessary in order to support Legacy mode.

You can find full documentation for that here: ISteamInput.

Controller Configuration

Players can set up fully customized input mappings for any game in their library, using native mode, legacy mode, or even a mix of both. These input mappings are called "controller configurations" and a player can make many different ones for a single game, as well as share them with other players online.

Input hierarchy

Physical Inputs

A "physical input" is an actual physical mechanism on any input device that the user interacts with to generate input data for their computer. These come in both digital and analog forms and examples include buttons, joysticks, Dpads, bumpers, triggers, switches, hats, trackballs, trackpads, gyroscopes, etc.

We're going to get into more abstract concepts soon so just remember that "physical inputs" are the little bits on the input device you actually wiggle around with your fingers (or toes, if you're so inclined).

Input Sources

An "input source" is a region of the device that can be thought of as a larger modular unit that can have any one of various different modes applied to it to change how it outputs data.

See, I told you we were going to get all abstract!

Let's bring it down to earth: what's the difference between a Dpad and four face buttons laid out in a diamond pattern?

input_dpad.pnginput_bpad.png

They both have four digital "buttons", but most Dpads are physically engineered in such a way that it's impossible to press Up+Down or Left+Right at the same time, whereas each face button can be pressed independently. However, Steam Input lets you impose the restrictions of a Dpad on your face buttons.

So although both the Dpad and the face button group are each composed of four individual "physical inputs," its convenient to think of the "Dpad" and the "face buttons" as their own units, so that we can change how the whole thing behaves.

The full list of recognized "input sources" is:

  • Left Trackpad
  • Right Trackpad
  • Center Trackpad
  • Left Joystick
  • Right Joystick
  • ABXY
  • DPAD
  • Left Trigger
  • Right Trigger
  • Gyro
  • Switch
NOTE: The "Switch" input source is a catch-all for all the physical inputs that don't belong to another group, such as back & start buttons, left & right shoulder buttons, and back paddle grips.

See also:

Input Source Modes

Input sources can have different modes imposed on them that change how they behave. These are called "input source modes." Although these are useful for digital inputs, the most frequent place you'll find yourself using input source modes is on analog controls, especially with trackpads, which can be configured in many different ways.

The full list of recognized "Input Source Modes" is:

  • Dpad
  • Four Buttons
  • Absolute Mouse
  • Relative Mouse
  • Joystick Move
  • Joystick Mouse
  • Joystick Camera
  • ScrollWheel
  • Trigger
  • TouchMenu
  • Mouse Joystick
  • Mouse Region
  • Radial Menu
  • Switches

See also:

Just to quickly summarize:

Physical Inputs:
The actual physical things you interact with on the device. Ex: the A button, the "up" input on the Dpad, etc.

Input Sources:
A larger grouping of individual physical inputs that can be grouped into a modular unit. The entire Dpad, the four face buttons, the entire left joystick assembly, etc.

Input Source Modes:
A specific behavior that you're forcing on an input source. Ex: "Make the face buttons act like a Dpad", "Make the left joystick act like four face buttons", etc.

Actions

Actions are the events that the Steam Input API uses to orchestrate everything. In native mode, your game doesn't get a "Button A pressed" event, it simply gets a "Jump" event (or whatever), and what kind of input causes "Jump" is entirely in the hands of the player.

Digital Actions

Digital actions are the simplest and most common kind of action. They are simply on or off, so the game simply polls repeatedly and listens for the state of these actions.

Analog Actions

Analog actions have one or more axes of data and are used for things like smoothly moving characters, steering cars, controlling cameras, etc. Standard joystick- and mouse- driven actions will usually have two axes, X and Y, but single-axis analog actions are possible too (such as those commonly bound to analog triggers); in this case the action data will still report two axes, but the Y axis will always be zero.

Action Name

All actions require identifying names such as "jump" or "punch". These string values are separate from the text the player sees (those are "Action Labels", and can be localized).

Action Handle

Polling for actions based on string names is costly and inefficient, so when your game bootstraps the API it must register all the actions by name, receiving corresponding integer action handles in return.

Action Origin

An "action origin" is a string that identifies what sort of input is bound to a given action in the player's input device configuration.

Action Sets

An action set is a logical grouping of associated actions. Only one action set can be active for any given input device at a given time. For instance, you can create a "menu" action set that is only active during menu sequences, as well as "driving", "walking", and "flying" action sets for a game like GTAV that features multiple vehicle and movement modes. Action sets exist both in native and legacy mode. In native mode, they are explicitly defined by the developer and the game will make API calls to designate which action set is currently active. In legacy mode, action set changes must be manually triggered by the player themselves. In both cases, action sets are a way to free up space on the input device by removing the need to permanently bind every action that could ever happen anywhere in the game and always leaving it on.

Action Set Layers

Action Set Layers are optional sets of action bindings which can be overlaid upon an existing set of controls. In contrast to Action Sets, layers draw their actions from the Action Set they exist within and do not wholesale replace what is already active when applied, but apply small modifications. These can consist of setting changes as well as adding or removing bindings from the base action set. More than one layer can be applied at a time and will be applied consecutively.

For more details, see Action Set Layers.

Physical Feedback

Beyond what happens on screen, some input devices have the ability to give feedback to the player through vibration and light.

Haptics

This allows for fine-grained physical sensations that help the player to orient where their hands and fingers are positioned on large touch surfaces, as well as to convey e.g. the virtual momentum of an emulated trackball. Haptics are supported on Steam Controllers and some Nintendo Switch controllers. Unsupported devices will ignore API calls for haptics.

Rumble

A more traditional form of physical feedback, rumble is caused by vibrating internal motors that shake the device. This feature is supported on the PlayStation 4 controller and the Xbox controllers (as well as many Xinput compatible generic devices). The Steam Controller does not have true rumble, but it does emulate an approximation using its haptics (and will therefore respond to the API calls for rumble).

LED

The Steam Controller and the PlayStation 4 controller both have a built in LED light on the controller. The Steam Controller's light is always white, but the PlayStation 4 controller features a fully programmable colored LED. Both of these devices will respond to API calls for changing the light color, but the Steam Controller will cast the color to monochrome and simply use it to control brightness, whereas on the PlayStation 4 controller it can be used to control both the color and the brightness. Unsupported devices will ignore API calls for the LED.